TsgcWS_API_Pusher 컴포넌트가 최신
Pusher Channels 프로토콜 사양에 맞춰 업데이트됐어요.
이번 릴리스에서는 비공개 암호화 채널 지원, 네 가지 새로운 presence 및 캐시 채널 이벤트,
두 가지 새로운 REST API 엔드포인트, 기존 엔드포인트의 향상된 쿼리 파라미터, 여러 버그 수정이 포함돼요.
모든 변경 사항은 하위 호환성을 유지해요. 기존 코드는 수정 없이 계속 작동해요.
목차
1. 비공개 암호화 채널 지원
Pusher Channels는 NaCl Secretbox(XSalsa20-Poly1305)를 사용해 이벤트 데이터의 종단 간 암호화를 제공하는 비공개 암호화 채널을 지원해요. Pusher 서버는 평문을 볼 수 없으며 통신하는 클라이언트만 메시지를 복호화할 수 있어요. TsgcWSPusherChannels 열거형에 두 가지 새로운 채널 유형이 추가됐어요:
| 열거형 값 | 채널 접두사 | 설명 |
|---|---|---|
pscPrivateEncryptedChannel |
private-encrypted- |
종단 간 암호화 비공개 채널. 데이터 페이로드가 채널별 공유 비밀로 암호화돼요. |
pscPrivateEncryptedCacheChannel |
private-encrypted-cache- |
위와 동일하며, 캐시 채널 동작도 포함해요. 마지막 이벤트가 새 구독자에게 전달돼요. |
TsgcWSPusherResponseAuthentication 클래스에 이제 SharedSecret 속성이 포함돼요. private-encrypted- 채널을 구독할 때 권한 부여 엔드포인트는 base64 인코딩된 채널별 공유 비밀을 반환해야 해요. 이 값을 OnPusherAuthentication 이벤트 핸들러에서 설정하세요:
procedure TForm1.sgcPusherAuthentication(Sender: TObject;
AuthRequest: TsgcWSPusherRequestAuthentication;
AuthResponse: TsgcWSPusherResponseAuthentication);
begin
// For private-encrypted channels, set the shared secret
// returned by your authorization server
AuthResponse.Secret := 'your-app-secret';
AuthResponse.SharedSecret := 'base64-encoded-per-channel-key';
end;암호화 채널 구독
// Subscribe to a private-encrypted channel
sgcPusher.Subscribe('my-secret-channel', pscPrivateEncryptedChannel);
// Subscribe to a private-encrypted cache channel
sgcPusher.Subscribe('my-secret-cache', pscPrivateEncryptedCacheChannel);암호화 채널에 발행
// Client events work on private-encrypted channels just like private channels
sgcPusher.Publish('my-event', 'my-secret-channel',
pscPrivateEncryptedChannel, '{"message":"Hello encrypted!"}');2. 새로운 WebSocket 이벤트
이전에 처리되지 않던 Pusher 내부 프로토콜 메시지를 처리하기 위해 네 가지 새로운 이벤트가 추가됐어요. 이 이벤트들은 해당 pusher_internal: 메시지가 WebSocket 연결을 통해 도착할 때 자동으로 발송돼요.
| 이벤트 속성 | 프로토콜 메시지 | 설명 |
|---|---|---|
OnPusherMemberAdded |
pusher_internal:member_added |
새 사용자가 presence 채널에 참여하면 발생해요. 채널 이름, 사용자 ID, 사용자 정보를 제공해요. |
OnPusherMemberRemoved |
pusher_internal:member_removed |
사용자가 presence 채널을 떠나면 발생해요. 채널 이름, 사용자 ID, 사용자 정보를 제공해요. |
OnPusherSubscriptionCount |
pusher_internal:subscription_count |
채널의 구독 수가 변경되면 발생해요. Pusher 대시보드에서 활성화해야 해요. |
OnPusherCacheMiss |
pusher_internal:cache_miss |
캐시된 이벤트가 없는 캐시 채널을 구독할 때 발생해요. |
OnPusherMemberAdded / OnPusherMemberRemoved
이 이벤트들은 채널 이름, 사용자 ID, 사용자 정보를 별도의 파라미터로 제공하는 새로운 TsgcWSPusherMemberEvent 콜백 유형을 사용해요:
TsgcWSPusherMemberEvent = procedure(Sender: TObject;
Channel, UserId, UserInfo: String) of object;procedure TForm1.sgcPusherMemberAdded(Sender: TObject;
Channel, UserId, UserInfo: String);
begin
Memo1.Lines.Add('User joined: ' + UserId + ' on ' + Channel);
if UserInfo '' then
Memo1.Lines.Add(' Info: ' + UserInfo);
end;
procedure TForm1.sgcPusherMemberRemoved(Sender: TObject;
Channel, UserId, UserInfo: String);
begin
Memo1.Lines.Add('User left: ' + UserId + ' from ' + Channel);
end;OnPusherSubscriptionCount
새로운 TsgcWSPusherSubscriptionCountEvent 콜백 유형을 사용해요. 이 이벤트는 Pusher 대시보드 설정에서 Subscription Count 기능을 활성화해야 해요.
TsgcWSPusherSubscriptionCountEvent = procedure(Sender: TObject;
Channel: String; SubscriptionCount: Integer) of object;procedure TForm1.sgcPusherSubscriptionCount(Sender: TObject;
Channel: String; SubscriptionCount: Integer);
begin
Memo1.Lines.Add(Channel + ' now has ' + IntToStr(SubscriptionCount) +
' subscribers');
end;OnPusherCacheMiss
새로운 TsgcWSPusherCacheMissEvent 콜백 유형을 사용해요. 이 이벤트는 캐시 채널(cache-, private-cache-, private-encrypted-cache-, presence-cache-)을 구독할 때 캐시된 이벤트가 없으면 발생해요.
TsgcWSPusherCacheMissEvent = procedure(Sender: TObject;
Channel: String) of object;procedure TForm1.sgcPusherCacheMiss(Sender: TObject; Channel: String);
begin
Memo1.Lines.Add('No cached event for channel: ' + Channel);
end;3. 새로운 REST API 메서드
TsgcWS_API_Pusher 컴포넌트에 배치 이벤트 엔드포인트와 사용자 연결 종료를 다루는 두 가지 새로운 서버 측 REST API 메서드가 추가됐어요.
| 메서드 | Pusher 엔드포인트 | 설명 |
|---|---|---|
TriggerBatchEvents |
POST /apps/{app_id}/batch_events |
단일 HTTP 요청으로 최대 10개의 이벤트를 트리거해요. 각 이벤트는 다른 채널을 대상으로 할 수 있어요. |
TerminateUserConnections |
POST /apps/{app_id}/users/{user_id}/terminate_connections |
특정 인증된 사용자의 모든 WebSocket 연결을 종료해요. |
TriggerBatchEvents
function TriggerBatchEvents(const aBatch: String): String;
aBatch 파라미터는 이벤트 객체의 batch 배열을 포함하는 JSON 문자열이에요. 각 객체에는 channel, name, data가 포함돼야 해요. 배치당 최대 10개의 이벤트예요.
var
vBatch, vResult: string;
begin
vBatch :=
'{"batch": [' +
' {"channel": "my-channel-1", "name": "my-event", "data": "{\"msg\":\"hello\"}"}' + ',' +
' {"channel": "my-channel-2", "name": "my-event", "data": "{\"msg\":\"world\"}"}' +
']}';
vResult := sgcPusher.TriggerBatchEvents(vBatch);
Memo1.Lines.Add(vResult);
end;TerminateUserConnections
function TerminateUserConnections(const aUserId: String): String;주어진 사용자의 모든 활성 WebSocket 연결을 강제로 종료해요. 모든 기기에서 사용자를 로그아웃하거나 권한 변경 후 접근을 취소할 때 유용해요. Pusher User Authentication이 설정돼 있어야 해요.
var
vResult: string;
begin
// Disconnect user "user-123" from all sessions
vResult := sgcPusher.TerminateUserConnections('user-123');
Memo1.Lines.Add(vResult);
end;4. 업데이트된 REST API 메서드
기존 세 가지 REST API 메서드에 추가적인 선택적 파라미터가 추가됐어요. 새 파라미터에는 모두 기본값이 있으므로 기존 코드는 완전히 하위 호환성을 유지해요.
TriggerEvent
이전 시그니처
function TriggerEvent(const aEventName, aChannel, aData: String): String;새 시그니처
function TriggerEvent(const aEventName, aChannel, aData: String;
const aSocketId: String = '';
const aInfo: String = ''): String;| 파라미터 | 설명 |
|---|---|
aSocketId |
이 소켓 ID를 이벤트 수신에서 제외해요. 발신자가 자신의 브로드캐스트를 받지 않도록 할 때 유용해요. |
aInfo |
반환할 속성의 쉼표로 구분된 목록. 유효한 값: subscription_count, user_count. |
var
vResult: string;
begin
// Trigger event, exclude the sender, and request subscription count
vResult := sgcPusher.TriggerEvent('my-event', 'my-channel',
'{"msg":"hello"}', sgcPusher.FSocket_id, 'subscription_count');
Memo1.Lines.Add(vResult);
// Response: {"channels":{"my-channel":{"subscription_count":5}}}
end;GetChannels
이전 시그니처
function GetChannels: String;새 시그니처
function GetChannels(
const aFilterByPrefix: String = '';
const aInfo: String = ''): String;| 파라미터 | 설명 |
|---|---|
aFilterByPrefix |
이름 접두사로 반환된 채널을 필터링해요. 예: presence-는 presence 채널만 반환해요. |
aInfo |
쉼표로 구분된 속성. 유효한 값: user_count(presence만), subscription_count. |
var
vResult: string;
begin
// List all presence channels with user counts
vResult := sgcPusher.GetChannels('presence-', 'user_count');
Memo1.Lines.Add(vResult);
// Response: {"channels":{"presence-room":{"user_count":3}}}
// List all channels (no filter) - backward-compatible call
vResult := sgcPusher.GetChannels;
Memo1.Lines.Add(vResult);
end;GetChannel
이전 시그니처
function GetChannel(const aChannel: String): String;새 시그니처
function GetChannel(const aChannel: String;
const aInfo: String = ''): String;| 파라미터 | 설명 |
|---|---|
aInfo |
쉼표로 구분된 속성. 유효한 값: subscription_count, user_count, cache. |
var
vResult: string;
begin
// Get channel info with subscription count and user count
vResult := sgcPusher.GetChannel('presence-room',
'subscription_count,user_count');
Memo1.Lines.Add(vResult);
// Response: {"occupied":true,"subscription_count":5,"user_count":3}
// Get basic channel info - backward-compatible call
vResult := sgcPusher.GetChannel('my-channel');
Memo1.Lines.Add(vResult);
end;5. 버그 수정
이번 릴리스에서 여러 버그가 발견되어 수정됐어요:
| 버그 | 영향 | 수정 |
|---|---|---|
Typo in DoReadEvent: 'puserh:ping' |
치명적 서버 핑이 인식되지 않아 클라이언트가 하트비트 요청을 놓쳤어요. 이로 인해 서버가 비활성으로 인해 클라이언트 연결을 끊을 수 있었어요. | 'pusher:ping'으로 수정됐어요. |
DoSendPong null access |
높음 null 체크 없이 JSON.Node['data'].Value에 접근하면 핑 메시지에 data 필드가 없을 때 접근 위반이 발생할 수 있었어요. |
null 체크가 추가됐어요. data가 없으면 {}로 기본값을 설정해요. |
GetUsers hardcoded prefix |
높음 메서드가 항상 채널 이름에 presence-를 앞에 추가해 사용자가 이미 전체 채널 이름을 전달한 경우 접두사가 두 배로 붙었어요(예: presence-presence-room). |
하드코딩된 접두사가 제거됐어요. 이제 사용자가 presence- 접두사를 포함한 전체 채널 이름을 전달해야 해요. |
GetUsers double semicolon |
낮음 메서드 끝에 불필요한 이중 세미콜론 ;;이 있었어요. |
추가 세미콜론이 제거됐어요. |
GetUsers의 호환성 변경 사항: GetUsers 메서드는 더 이상 presence-를 자동으로 앞에 추가하지 않아요. 코드에서 접두사 없이 채널 이름만 전달하는 경우(예: GetUsers('my-room')) 전체 이름을 포함하도록 업데이트해야 해요: GetUsers('presence-my-room').
6. 요약
| 분류 | 수 | 세부 사항 |
|---|---|---|
| 새로운 채널 유형 | 2 | pscPrivateEncryptedChannel, pscPrivateEncryptedCacheChannel |
| 새로운 WebSocket 이벤트 | 4 | OnPusherMemberAdded, OnPusherMemberRemoved, OnPusherSubscriptionCount, OnPusherCacheMiss |
| 새로운 REST 메서드 | 2 | TriggerBatchEvents, TerminateUserConnections |
| 업데이트된 REST 메서드 | 3 | TriggerEvent (+socket_id, +info), GetChannels (+filter, +info), GetChannel (+info) |
| 새로운 속성 | 1 | SharedSecret on TsgcWSPusherResponseAuthentication |
| 버그 수정 | 4 | Ping typo, pong null access, GetUsers prefix, double semicolon |
모든 변경 사항은 하위 호환성을 유지해요. 새 메서드 파라미터는 기본값을 사용하고 새 이벤트 속성은 선택 사항이에요. 유일한 동작 변경 사항은 GetUsers에 있으며, 더 이상 presence- 접두사를 자동으로 추가하지 않아요.