Skip to content

Tutorials

These tutorials build things on Felix one step at a time. Each has you write a small program, run it and compare what it prints with what the page says you should see. The demos run finished systems. The tutorials are where you write the code yourself.

The first three are independent. The last one uses all three ideas, so do it after the others.

Every tutorial shows Rust, Python, TypeScript and C#, and the language you pick on one page stays selected on the others. The C client is callback based, so the first three tutorials end with a complete C program instead of a tab per step, and the last has no C version. The C calls it makes are the ones from the earlier tutorials.

Conditional cache writes, which the lease in the third tutorial needs, are in the Rust, C# and C clients. The Python and TypeScript bindings do not have them yet, so that step has no tab for them.

The code in each tutorial is compiled as part of the documentation tests, so the snippets match the client APIs they were written against.

The Python examples use the asyncio client, felix.AsyncClient, because it lets every call carry a time limit. The synchronous felix.Client takes the same calls without await.

Every call to the broker in these programs has a time limit of ten seconds, and a call that waits on purpose, such as a consumer group poll, gets its wait on top. A program that waits on a broker for ever is hard to tell from one that is working, so the limit turns a stuck call into an error. Each language sets it differently:

  • Rust wraps the call in tokio::time::timeout through a small bounded helper.
  • Python wraps the awaitable in asyncio.wait_for.
  • TypeScript races the promise against a timer, because the client takes no timeout argument. The call itself is not cancelled and may still finish.
  • C# passes a CancellationToken from a CancellationTokenSource that expires after the limit.
  • C waits for each callback with a deadline, and ends the program if the broker does not answer in time, because the callback may still run later.

A call that times out may or may not have reached the broker, so a write that times out is not known to have failed. Reads that wait for events by design, such as a subscription or a watch, have no limit of their own. Where a tutorial reads with a timeout, it is part of the example.

The tutorials use the Felix 0.7 client API. Install the client libraries at 0.7.3, as each language tab shows. The compose file below is the one tagged v0.7.3. It starts the broker, control plane and felixctl at the version it names.

The tutorials run against the development stack from the quickstart: a control plane, one broker with durable storage, and credentials for a tenant named dev with a namespace named default. It needs Docker or Podman. The credentials work on your machine only.

Pick your container engine. The choice applies to every command on these pages. With Podman, start the machine first on macOS or Windows (podman machine start), and have docker-compose 2.20 or later installed: podman compose hands the file to it, and podman-compose does not run this file correctly. Docker or Podman has the details.

Terminal window
curl -fsSLO https://raw.githubusercontent.com/GetFelix/felix/v0.7.3/compose.yaml
docker compose up # stays in the foreground and prints the logs
# or, in the background:
docker compose up -d
docker compose logs -f

Run up from the directory that holds compose.yaml. In the foreground form the stack prints its logs and keeps the terminal, so leave it running. In another terminal in the same directory, copy out the client token and the broker’s certificate and write the settings every tutorial reads to an env file, with absolute paths so it works from any directory:

Terminal window
docker compose exec -T felix-broker cat /var/lib/felix/client.jwt > felix-dev.jwt
docker compose exec -T felix-broker cat /var/lib/felix/broker-cert.pem > felix-dev.pem
cat > felix-tutorial.env <<EOF
export FELIX_BROKERS=127.0.0.1:5000
export FELIX_AUTH_TENANT=dev
export FELIX_AUTH_TOKEN="$(cat felix-dev.jwt)"
export FELIX_CA_FILE="$PWD/felix-dev.pem"
export COMPOSE_FILE="$PWD/compose.yaml"
EOF
source felix-tutorial.env

The stack publishes ports 5000 to 5003 (UDP) and 8080, 8081 and 8443 (TCP) on 127.0.0.1. If up fails because a port is in use, another container usually holds it, often another Felix stack. On Podman, lsof names the holder as gvproxy, the process that forwards every published port, so ask the engine which container it is and stop that stack first:

Terminal window
docker ps --format '{{.Names}}\t{{.Ports}}'

Run source /path/to/felix-tutorial.env in every terminal you use for the tutorials, the programs and felixctl alike. COMPOSE_FILE lets compose find the stack from any directory.

The token lasts a day. The broker makes a new certificate every time it starts, so copy the file again after a restart. The tutorials create their streams and caches with felixctl, which the compose file runs for you as docker compose run --rm felixctl, or podman compose run --rm felixctl with Podman, where the env file already sets PODMAN_COMPOSE_PROVIDER. To use one installed on your machine, see felixctl and the Docker Compose page for adding a context.

Then set up your language. Each tutorial is one program. Copy the blocks for your language, in order, into that tutorial’s file, then run the file with a mode argument, as the tutorial’s “Run it” section shows. Every terminal you run a program from needs the exported FELIX_* settings above.

Tutorial Program name
Your first stream first_stream (C: first-stream)
A work queue work_queue (C: work-queue)
Cache, leases and watches cache_leases_watches (C: cache-leases-watches)
Build an app build_an_app (no C version)

The file names below follow each language’s convention.

Terminal window
cargo new felix-tutorial && cd felix-tutorial
cargo add felix-client@0.7.3 anyhow bytes serde_json
cargo add tokio --features rt-multi-thread,macros,time,fs,io-util

Each tutorial is one binary in this project. Put its blocks in src/bin/first_stream.rs, src/bin/work_queue.rs, src/bin/cache_leases_watches.rs and src/bin/build_an_app.rs, and run one with cargo run --bin first_stream -- <mode>. See the Rust client for the API.

If you build Felix from source instead of using the compose stack, see Installation and Running a broker yourself. A broker you run yourself needs a tenant, a token and a certificate; set the four variables above to match.