github.com/anycable/anycable-go@v1.5.1/docs/long_polling.md (about)

     1  # Long polling support
     2  
     3  <p class="pro-badge-header"></p>
     4  
     5  AnyCable Pro supports alternative transport protocols, such as long polling. Even though WebSockets are widely supported, they still can be blocked by corporate firewalls and proxies. Long polling is a simplest alternative for such cases, especially if you want to support legacy browsers or clients without official client SDKs.
     6  
     7  **IMPORTANT:** Long-polling sessions are not distributed by design (at least for now). For AnyCable-Go clusters, **sticky sessions must be used** for polling connections.
     8  
     9  ## Usage
    10  
    11  First, you need to enable long polling support in `anycable-go`:
    12  
    13  ```sh
    14  $ anycable-go --poll
    15  
    16    INFO 2023-06-29T03:44:22.460Z context=main Starting AnyCable 1.4.0-pro-72d0c60 (with mruby 1.2.0 (2015-11-17)) (pid: 34235, open file limit: 122880, gomaxprocs: 8, netpoll: true)
    17    ...
    18    INFO 2023-06-29T03:44:22.462Z context=main Handle long polling requests at http://0.0.0.0:8080/lp (poll_interval: 15, keepalive_timeout: 5)
    19  ```
    20  
    21  Now you can use the `/lp` endpoint to establish a long polling connection. Let's see how we can do that at the client side.
    22  
    23  ### Using with AnyCable JS SDK
    24  
    25  [AnyCable JS client][anycable-client] provides long polling support by the means of the [@anycable/long-polling][] plugin. You can use it as follows:
    26  
    27  ```js
    28  import { createCable } from '@anycable/web'
    29  import { LongPollingTransport } from '@anycable/long-polling'
    30  
    31  // Create a transport object and pass the URL to the AnyCable server's long polling endpoint
    32  const lp = new LongPollingTransport('http://my.anycable.host/lp')
    33  
    34  // Pass the transport to the createCable or createConsumer function via the `fallbacks` option
    35  export default createCable({fallbacks: [lp]})
    36  ```
    37  
    38  That's it! Now your client will fallback to long polling if WebSocket connection can't be established.
    39  
    40  See full documentation [here][@anycable/long-polling]
    41  
    42  ### Using with a custom client
    43  
    44  You can use any HTTP client to communicate with AnyCable via a long polling endpoint.
    45  
    46  #### Establishing a connection
    47  
    48  To establish a connection, client MUST send a `POST` request to the `/lp` endpoint. The authentication is performed based on the request data (cookies, headers, etc.), i.e., similar to WebSocket connections.
    49  
    50  Client MAY send commands along with the initial request. The commands are processed by server only if authentication is successful. See below for the commands format.
    51  
    52  If authentication is successful, the server MUST respond with a 20x status code and a unique poll session identifier in the `X-Anycable-Poll-ID` response header. The response body MAY include messages for the client.
    53  
    54  If authentication is unsuccessful, the server MUST respond with a 401 status code. The response body MAY include messages for the client.
    55  
    56  All other status codes are considered as errors.
    57  
    58  #### Polling
    59  
    60  Client MUST send a `POST` request to the `/lp` endpoint with the `X-Anycable-Poll-ID` header set to the poll session identifier received during the initial connection to receive messages from the server.
    61  
    62  Client MAY send commands along with the poll request.
    63  
    64  #### Stale session
    65  
    66  If client doesn't send a poll request for a certain period of time (see `--poll_keepalive_timeout` option below), the server MUST close the poll session and respond with a 401 status code to the next polling request with the session's ID. Server MAY send a `session_expired` disconnect message to the client.
    67  
    68  #### Communication format
    69  
    70  Both client and server MUST use JSONL (JSON Lines) format for communication. JSONL is a sequence of JSON objects separated by newlines (`\n`). The last object MUST be followed by a newline.
    71  
    72  For example, client MAY send the following commands along the initial request:
    73  
    74  ```json
    75  {"command":"subscribe", "identifier":"chat_1"}
    76  {"command":"subscribe","identifier":"presence_1"}
    77  ```
    78  
    79  Server MAY respond with the following messages in the response body:
    80  
    81  ```json
    82  {"type":"welcome"}
    83  {"type":"confirm_subscription","identifier":"chat_1"}
    84  {"type":"confirm_subscription","identifier":"presence_1"}
    85  ```
    86  
    87  ## Configuration
    88  
    89  The following options are available:
    90  
    91  - `--poll_path` (`ANYCABLE_POLL_PATH`) (default: `/lp`): a long polling endpoint path.
    92  - `--poll_interval` (`ANYCABLE_POLL_INTERVAL`) (default: 15): polling interval in seconds.
    93  - `--poll_flush_interval` (`ANYCABLE_POLL_FLUSH_INTERVAL`) (default: 500): defines for how long to buffer server-to-client messages before flushing them to the client (in milliseconds).
    94  - `--poll_max_request_size` (`ANYCABLE_POLL_MAX_REQEUEST_SIZE`) (default: 64kB): maximum acceptable request body size (in bytes).
    95  - `--poll_keepalive_timeout` (`ANYCABLE_POLL_KEEPALIVE_TIMEOUT`) (default: 5): defines for how long to keep a poll session alive between requests (in seconds).
    96  
    97  ## CORS
    98  
    99  Server responds with the `Access-Control-Allow-Origin` header set to the value of the `--allowed_origins` option (default: `*`). If you want to restrict the list of allowed origins, you can pass a comma-separated list of domains to the option. See [documentation](./configuration.md).
   100  
   101  ## Instrumentation
   102  
   103  When long polling enabled, the following metrics are available:
   104  
   105  - `long_poll_clients_num`: number of active long polling clients.
   106  - `long_poll_stale_requests_total`: number of stale requests (i.e., requests that were sent after the poll session was closed).
   107  
   108  [anycable-client]: https://github.com/anycable/anycable-client
   109  [@anycable/long-polling]: https://github.com/anycable/anycable-client/tree/master/packages/long-polling