Skip to main content

Connect & Subscribe

Now that you're able to sign tokens with the correct claims, we'll use a token to connect to the WebSocket, subscribe to a channel, and publish/receive messages from the command line.

The purpose of this guide is to demonstrate how the pieces fit together - signing, connecting, subscribing, and message publishing.

If you want to try things out with a point-and-click graphical interface instead, check out the web console.

Sign a tokenโ€‹

First, we'll sign a token with an exp claim, a scope claim, and a channels claim for the "get-started-with-hotsock" channel allowing subscribe.

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "exp": 1693963905,
  "channels": {
    "get-started-with-hotsock": {
      "subscribe": true
    }
  },
  "scope": "connect"
}

The signed, encoded token value is eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTM5NjM5MDUsImNoYW5uZWxzIjp7ImdldC1zdGFydGVkLXdpdGgtaG90c29jayI6eyJzdWJzY3JpYmUiOnRydWV9fSwic2NvcGUiOiJjb25uZWN0In0.Ls62aNTexRTZGJfp5ei-hUO4XwhEn5hwgxBuUPD77k4. Here's the encoded/decoded breakdown of this token.

In a real application, a signed token is safe to give to client applications. If it is tampered with in any way before being used, its signature will no longer be valid and the system will reject it from being used.

Connect to the WebSocketโ€‹

Using the WebSocketsAwsWssUrl value from the CloudFormation stack output, connect to the WebSocket using wscat. In a real-world application you'd likely connect with a web browser or other client device, but wscat demonstrates the process.

Set the token value in the token query parameter (note the ?token=eyJ... portion for setting the query parameter).

wscat -c "wss://1ycut2oy9h.execute-api.us-east-1.amazonaws.com/v1?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTM5NjM5MDUsImNoYW5uZWxzIjp7ImdldC1zdGFydGVkLXdpdGgtaG90c29jayI6eyJzdWJzY3JpYmUiOnRydWV9fSwic2NvcGUiOiJjb25uZWN0In0.Ls62aNTexRTZGJfp5ei-hUO4XwhEn5hwgxBuUPD77k4"
Connected (press CTRL+C to quit)
< {"event":"hotsock.connected","data":{"connectionId":"JCnTZd_KoAMCF-A=","connectionExpiresAt":"2024-10-13T19:09:23Z","connectionSecret":"1FfpK4PHV1B7ZryUSCsN"},"meta":{"uid":null,"umd":null}}
>

If the token is valid, you'll be connected and will receive an initial hotsock.connected message containing the connection ID. ๐ŸŽ‰

Subscribe to a channelโ€‹

You're connected, but are not subscribed to any channels. Until you subscribe, you won't receive any messages (except for periodic keep-alive messages, if enabled).

Let's subscribe to the "get-started-with-hotsock" channel authorized in the token. Send a message with the hotsock.subscribe event to the get-started-with-hotsock channel in JSON format.

> {"event":"hotsock.subscribe", "channel":"get-started-with-hotsock"}

You'll immediately receive confirmation of the subscription.

< {"event":"hotsock.subscribed","channel":"get-started-with-hotsock","data":{},"meta":{"uid":null,"umd":null}}

Now, any messages sent to the "get-started-with-hotsock" channel will be sent to you, the only current subscriber of this channel.

Send and receive a messageโ€‹

Lambda direct function invocationโ€‹

Using the AWS CLI, we'll invoke the function from PublishFunctionArn to send a message to our channel. Copy the Arn from the stack output to the function name argument.

aws lambda invoke \
  --function-name arn:aws:lambda:us-east-1:111111111111:function:Hotsock-Publishing-1K4R55PICWM9Q-PublishFunction-ZsQtKbbCqUVF \
  --payload '{"channel":"get-started-with-hotsock", "event":"welcome", "data":"๐Ÿ‘‹ Hello from Hotsock! ใ“ใ‚“ใซใกใฏ"}' \
  --cli-binary-format raw-in-base64-out \
  /dev/stdout

The expected response to this function invocation is {"id":null,"channel":"get-started-with-hotsock","event":"welcome"}. More details on publishing with Lambda as well as request and response attributes in message publishing.

Over in your WebSocket connection window, the published message will be received by you, the channel subscriber.

< {"id":"01H2BSNHFJXKF2XDFD8KMM36FF","event":"welcome","channel":"get-started-with-hotsock","data":"\ud83d\udc4b Hello from Hotsock! \u3053\u3093\u306b\u3061\u306f"}

If you repeatedly invoke the publish function, you'll see additional messages received on the WebSocket.

HTTP URLโ€‹

As an alternative to using the AWS SDK to invoke Lambda directly, you can send backend-initiated messages using a standard HTTPS POST request.

Grab the PublishHttpApiUrl CloudFormation stack output value for the URL. The secret key is a 40-character string that can be found on the page provided in the HttpApiSecretKey1ConsoleUrl or HttpApiSecretKey2ConsoleUrl output.

Given a URL of https://k6rcy6a2leyehqhlphlwkkuppm0xxubn.lambda-url.us-east-1.on.aws/publish and a primary secret value of BFS164OqJg0UHy0q8cfU6QvUo23kB0lPX1fb9Hae, we'll make a POST request with cURL to that endpoint with the secret key set as a Bearer token in the Authorization header.

curl -X "POST" "https://k6rcy6a2leyehqhlphlwkkuppm0xxubn.lambda-url.us-east-1.on.aws/publish" \
     -i \
     -H 'Content-Type: application/json; charset=utf-8' \
     -H 'Authorization: Bearer BFS164OqJg0UHy0q8cfU6QvUo23kB0lPX1fb9Hae' \
     -d $'{
        "channel": "get-started-with-hotsock",
        "event": "welcome",
        "data": "๐Ÿ‘‹ Hello from Hotsock! ใ“ใ‚“ใซใกใฏ"
      }'

The expected response to this request is {"id":null,"channel":"get-started-with-hotsock","event":"welcome"} with a 202 Accepted HTTP response code. More details on publishing with HTTP as well as request and response attributes in message publishing.

Over in your WebSocket connection window, the published message will be received by you, the channel subscriber.

< {"id":"01H2C4Z3PFFJR6RG5D6A12HM92","event":"welcome","channel":"get-started-with-hotsock","data":"\ud83d\udc4b Hello from Hotsock! \u3053\u3093\u306b\u3061\u306f"}

If you change the event name or the data value in the request payload and repeatedly submit the request, you'll see additional messages received on the WebSocket.