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.
Languages
Section titled “Languages”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.
Time limits
Section titled “Time limits”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::timeoutthrough a smallboundedhelper. - 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
CancellationTokenfrom aCancellationTokenSourcethat 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.
Set up once
Section titled “Set up once”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.
curl -fsSLO https://raw.githubusercontent.com/GetFelix/felix/v0.7.3/compose.yamldocker compose up # stays in the foreground and prints the logs# or, in the background:docker compose up -ddocker compose logs -fcurl -fsSLO https://raw.githubusercontent.com/GetFelix/felix/v0.7.3/compose.yamlexport PODMAN_COMPOSE_PROVIDER=docker-composepodman compose up # stays in the foreground and prints the logs# or, in the background:podman compose up -dpodman compose logs -fRun 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:
docker compose exec -T felix-broker cat /var/lib/felix/client.jwt > felix-dev.jwtdocker compose exec -T felix-broker cat /var/lib/felix/broker-cert.pem > felix-dev.pem
cat > felix-tutorial.env <<EOFexport FELIX_BROKERS=127.0.0.1:5000export FELIX_AUTH_TENANT=devexport FELIX_AUTH_TOKEN="$(cat felix-dev.jwt)"export FELIX_CA_FILE="$PWD/felix-dev.pem"export COMPOSE_FILE="$PWD/compose.yaml"EOFsource felix-tutorial.envexport PODMAN_COMPOSE_PROVIDER=docker-composepodman compose exec -T felix-broker cat /var/lib/felix/client.jwt > felix-dev.jwtpodman compose exec -T felix-broker cat /var/lib/felix/broker-cert.pem > felix-dev.pem
cat > felix-tutorial.env <<EOFexport FELIX_BROKERS=127.0.0.1:5000export FELIX_AUTH_TENANT=devexport FELIX_AUTH_TOKEN="$(cat felix-dev.jwt)"export FELIX_CA_FILE="$PWD/felix-dev.pem"export COMPOSE_FILE="$PWD/compose.yaml"export PODMAN_COMPOSE_PROVIDER=docker-composeEOFsource felix-tutorial.envThe 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:
docker ps --format '{{.Names}}\t{{.Ports}}'podman 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.
cargo new felix-tutorial && cd felix-tutorialcargo add felix-client@0.7.3 anyhow bytes serde_jsoncargo add tokio --features rt-multi-thread,macros,time,fs,io-utilEach 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.
You need Python 3.10 or later. Make a virtual environment for the tutorials:
python3 -m venv .venv && . .venv/bin/activatepip install felix-client==0.7.3Activate it again in every terminal. The module is felix. Each tutorial is one file: first_stream.py,
work_queue.py, cache_leases_watches.py and build_an_app.py. Run one with
python3 first_stream.py <mode>. See the Python client.
mkdir felix-tutorial && cd felix-tutorialnpm install felix-client@0.7.3npm install -D tsxThe programs are ES modules with top-level await, so each tutorial is one
.mts file: first-stream.mts, work-queue.mts, cache-leases-watches.mts
and build-an-app.mts. Run one with npx tsx first-stream.mts <mode>. See the
TypeScript client.
Each tutorial is its own console project. For the first one:
dotnet new console -o FirstStream && cd FirstStreamdotnet add package Felix.Client --version 0.7.3Make WorkQueue, CacheLeasesWatches and BuildAnApp the same way. A
tutorial’s blocks replace the template’s Program.cs in its project, and from that directory run
dotnet run -- <mode>. See the C# client.
Each tutorial’s C program is one file: first-stream.c, work-queue.c and
cache-leases-watches.c. Download the v0.7.3 release archive for your
platform as the C client page describes, unpack it and
save the program inside the unpacked directory. On Linux x64:
curl -fLO https://github.com/GetFelix/felix/releases/download/v0.7.3/libfelix-v0.7.3-linux-x64.tar.gztar xzf libfelix-v0.7.3-linux-x64.tar.gzcd libfelix-v0.7.3-linux-x64cc -std=c11 -pthread -I include first-stream.c -L lib -lfelix \ -Wl,-rpath,"$PWD/lib" -o first-streamOn macOS with Apple silicon, use the osx-arm64 archive. The command is the
same and links lib/libfelix.dylib:
curl -fLO https://github.com/GetFelix/felix/releases/download/v0.7.3/libfelix-v0.7.3-osx-arm64.tar.gztar xzf libfelix-v0.7.3-osx-arm64.tar.gzcd libfelix-v0.7.3-osx-arm64cc -std=c11 -pthread -I include first-stream.c -L lib -lfelix \ -Wl,-rpath,"$PWD/lib" -o first-streamThe release also has linux-arm64 and osx-x64 archives, and zip archives
for Windows. Change the file and output names for the other tutorials, and
run the result as ./first-stream <mode>. To build from source instead, see
the C client page.
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.
