Proxy events to the backend
It's possible to proxy some client connection events from Centrifugo to the application backend and react to them in a custom way. For example, it's possible to authenticate connection via request from Centrifugo to application backend, refresh client sessions and answer to RPC calls sent by a client over bidirectional connection. Also, you may control subscription and publication permissions using these hooks.
The list of events that can be proxied:
connect
– called when a client connects to Centrifugo, so it's possible to authenticate user, return custom data to a client, subscribe connection to several channels, attach meta information to the connection, and so on. Works for bidirectional and unidirectional transports.refresh
- called when a client session is going to expire, so it's possible to prolong it or just let it expire. Can also be used just as a periodical connection liveness callback from Centrifugo to app backend. Works for bidirectional and unidirectional transports.subscribe
- called when clients try to subscribe on a channel, so it's possible to check permissions and return custom initial subscription data. Works for bidirectional transports only.publish
- called when a client tries to publish into a channel, so it's possible to check permissions and optionally modify publication data. Works for bidirectional transports only.sub_refresh
- called when a client subscription is going to expire, so it's possible to prolong it or just let it expire. Can also be used just as a periodical subscription liveness callback from Centrifugo to app backend. Works for bidirectional and unidirectional transports.rpc
- called when a client sends RPC, you can do whatever logic you need based on a client-provided RPC method and params. Works for bidirectional transports only.
At the moment Centrifugo can proxy these events over two protocols:
- HTTP (JSON payloads)
- GRPC (Protobuf messages)
HTTP proxy
HTTP proxy in Centrifugo converts client connection events into HTTP calls to the application backend.
HTTP request structure
All proxy calls are HTTP POST requests that will be sent from Centrifugo to configured endpoints with a configured timeout. These requests will have some headers copied from the original client request (see details below) and include JSON body which varies depending on call type (for example data sent by a client in RPC call etc, see more details about JSON bodies below).
Proxy HTTP headers
The good thing about Centrifugo HTTP proxy is that it transparently proxies original HTTP request headers in a request to app backend. In most cases this allows achieving transparent authentication on the application backend side. But it's required to provide an explicit list of HTTP headers you want to be proxied, for example:
{
...
"proxy_http_headers": [
"Origin",
"User-Agent",
"Cookie",
"Authorization",
"X-Real-Ip",
"X-Forwarded-For",
"X-Request-Id"
]
}
Alternatively, you can set a list of headers via an environment variable (space separated):
export CENTRIFUGO_PROXY_HTTP_HEADERS="Cookie User-Agent X-B3-TraceId X-B3-SpanId" ./centrifugo
Centrifugo forces the Content-Type
header to be application/json
in all HTTP proxy requests since it sends the body in JSON format to the application backend.
Proxy GRPC metadata
When GRPC unidirectional stream is used as a client transport then you may want to proxy GRPC metadata from the client request. In this case you may configure proxy_grpc_metadata
option. This is an array of string metadata keys which will be proxied. These metadata keys transformed to HTTP headers of proxy request. By default no metadata keys are proxied.
See below the table of rules how metadata and headers proxied in transport/proxy different scenarios.