Handlers
WebSocket Handler
Note
This is an Enterprise only policy at this time. Please contact us to trial this or sign up for an Enterprise account.
The WebSocket Handler enables you to manage WebSocket connections to your backend WebSocket APIs. It can be configured alongside other existing policies like Rate Limiting, API Keys, etc. and is available for use on all environments.
This handler is currently in beta and only configurable via the JSON View on a
project's Route Designer or directly in your project's *.oas.json
file.
Setup in routes.oas.json#
Configuration of the WebSocket Handler is similar to other available handlers.
Set the name of the path that your WebSocket API route will use, set the use of
the webSocketHandler
export from @zuplo/runtime
module in the handler
configuration and use the rewritePattern
property inside of options
to point
to your service's WebSocket API endpoint.
Your configuration will look like below:
Handler Options#
The WebSocket Handler can be configured via options
property. It has the
following configuration properties
rewritePattern
- the URL the incoming pathname will be appended to.
Similar to other handlers using rewritePattern
, it supports Javascript string
interpolation syntax and can be used to shape the URL based on data from the
incoming request and environment variables defined in the project.
The following objects are available for substitution:
env
- the environment object, to access Environment Variablesrequest: ZuploRequest
- the fullZuploRequest
objectcontext: ZuploContext
- theZuploContext
object without functions.params: Record<string, string>
- The parameters of the route. For example,params.productId
would be the value of:productId
in a route.query: Record<string, string>
- The query parameters of the route. For example,query.filterBy
would be the value of?filterBy=VALUE
.headers: Headers
- the incoming request's headers objecturl: string
- The full incoming request as a stringhost: string
- Thehost
portion of the incoming URLhostname: string
- Thehostname
portion of the incoming URLpathname: string
- Thepathname
portion of the incoming URLport: string
- Theport
portion of the incoming URLsearch
- Thesearch
portion of the incoming URL
Use the following methods to encode portions of the URL:
encodeURIComponent
: TheencodeURIComponent()
function encodes a URI by replacing each instance of certain characters with escape sequences.e
: An alias toencodeURIComponent
to help keep URLs more readable. Can be used like${e(params.productId)}
Example Values#
A few examples of the values of various substitutions.
${headers.get("content-type")}
-"application/json"
${host}
-"example.com:8080"
${hostname}
-"example.com"
${method}
-"GET"
${origin}
-"https://example.com"
${params.productId}
-":productId"
${pathname}
-"/v1/products/:productId"
${port}
-"8080"
${protocol}
-"https:"
${query.category}
-"cars"
${search}
-"?category=cars"
${url}
-"https://example.com:8080/v1/products/:productId?category=cars"
${env.BASE_URL}
-"https://example.com"
Different Backends per Environment#
It's common to want to use different backends for your production, staging and preview environments. This can be easily achieved by using environment variables to specify the origin of the backend.
For example,
Using the rewritePattern
in options
you can combine the BASE_PATH
environment variable, say https://example.com
to achieve this.