Push messaging using Fanout
- Platform:
- Fastly Compute
- Language:
- Rust
- Repo:
- https://github.com/fastly/compute-starter-kit-rust-fanout
Use this starter
Using the Fastly CLI, create a new project using this starter somewhere on your computer:
$ fastly compute init --from=https://github.com/fastly/compute-starter-kit-rust-fanout
Or click the button below to create a GitHub repository, provision a Fastly service, and set up continuous deployment:
How it works
For test requests (Paths under /test/
), the app is actually invoked twice.
Initially, a client request arrives at the app without having been routed through the Fanout proxy yet. The app checks for this via the presence of a
Grip-Sig
header. If that header is not present, the app callscreateFanoutHandoff(request, 'self')
and exits. This tells the subsystem that the connection should be routed through Fanout, and is used for HTTP requests controlled by GRIP.Since
self
refers to the same app, a second request is made to the same app, this time coming through Fanout. The app checks for this, and then handles the request accordingly (inhandleTest()
).
Non-test requests are simply forwarded through the Fanout proxy and on to the origin.
[!IMPORTANT] The starter kit forwards all non-test traffic through Fanout to the origin. In a production environment, be selective about the requests you send through Fanout. See What to hand off to Fanout for a discussion on this topic.
Setup
The app expects a configured backend named "origin"
. It forwards all non-test requests through Fanout to this backend.
Additionally, for the test endpoints to work, the app expects a configured backend named "self"
that points back to app itself. For example, if the service has a domain foo.edgecompute.app
, then you'll need to create a backend on the service named "self"
with the destination host set to foo.edgecompute.app
and port 443. Also set "Override Host" to the same host value.
You'll also need to enable Fanout on your Fastly service to run this application. To enable Fanout on your service, type:
fastly products --enable=fanout
Local testing
To test Fanout features in the local testing environment, first obtain Pushpin, the open-source GRIP proxy server that Fastly Fanout is based upon, and make sure it is available on the system path.
Create a Fastly Compute project based on this starter kit.
mkdir my-fanout-projectcd my-fanout-projectfastly compute init --from=https://github.com/fastly/compute-starter-kit-rust-fanout
The fastly.toml
file included in this starter kit includes a local_server.pushpin
section:
[local_server.pushpin]enable = true
Run the starter kit:
fastly compute serve
The Fastly CLI starts Pushpin and then starts the starter kit app at http://localhost:7676/.
Test Endpoints
The app handles requests to the following endpoints at the edge:
/test/stream
: HTTP streaming oftext/plain
/test/sse
: SSE (streaming oftext/event-stream
)/test/long-poll
: Long-polling/test/websocket
: bidirectional WebSocket- In the example, the WebSocket endpoint is set up to echo back any messages it receives from the client.
Connecting to any of these endpoints subscribes the connection to channel "test"
.
On the local testing environment, data can be sent to the connections via the GRIP publish endpoint at http://localhost:5561/publish/
. For example, here's a curl command to send a WebSocket message:
curl \ -d '{"items":[{"channel":"test","formats":{"ws-message":{"content":"hello"}}}]}' \ http://localhost:5561/publish/
Once deployed to your Fastly service, the GRIP publish endpoint is at https://api.fastly.com/service/{service-id}/publish/
. Here's the same example on Fastly service:
curl \ -H "Authorization: Bearer {fastly-api-token}" \ -d '{"items":[{"channel":"test","formats":{"ws-message":{"content":"hello"}}}]}' \ https://api.fastly.com/service/{service-id}/publish/
How it works
Non-test requests are simply forwarded through the Fanout proxy and on to the origin.
For test requests, the app is actually invoked twice.
Initially, a client request arrives at the app without having been routed through the Fanout proxy yet. The app checks for this via the presence of a
Grip-Sig
header. If that header is not present, the app callsreq.handoff_fanout("self")
and exits. This tells the subsystem that the connection should be routed through Fanout, and is used for HTTP requests controlled by GRIP.Since
self
refers to the same app, a second request is made to the same app, this time coming through Fanout. The app checks for this, and then handles the request accordingly (inhandle_test()
).
Note
This app is not currently supported in Fastly's local development server, as the development server does not support Fanout features. To experiment with Fanout, you will need to publish this project to your Fastly Compute service. using the fastly compute publish
command.
Next steps
Starters are a good way to bootstrap a project. For more specific use cases, and answers to common problems, try our library of code examples.