Tutorial · first successful path

Follow one event from local request to accepted identity

You will start the local gateway, send one synthetic event, inspect its response, and prove that replaying the same identity does not create a second logical event.

Time: 20 minutesPrerequisites: Go 1.22, Make, DockerProduction access: none

Learning goal · 20 minutes

By the end, you can

start the local gateway from a known-good build;
send one synthetic event and read its acceptance;
explain why a retry keeps the same event ID.

Start from a known-good build

5 min

bashmake ingest-test

Checkpoint: contract and consumer suites pass. If they do not, stop here; the tutorial should not teach around a broken baseline.

Start the local gateway

4 min

bashmake ingest-run

Leave the process running when the log reports listening on port 8443. The local queue is provided by the development stack; no staging credential is required.

Send one synthetic event

5 min

bashcurl -k -i https://127.0.0.1:8443/events \
  -H 'X-Request-Id: req_tutorial_01' \
  -d '{"id":"evt_learn","type":"tutorial.ping"}'

Use a synthetic type and stable ID so the next step can reason about identity.

Checkpoint: response is 202, echoes the request ID, and returns {"id":"evt_learn","status":"accepted"}.

Repeat the identity and inspect the result

4 min

Run the same request again without changing evt_learn. The service may return the original acceptance or an idempotent acknowledgement, but it must not create a second warehouse row.

This is the most important lesson in the tutorial: request retries preserve event identity.

Stop at the lesson boundary

2 min

You can start the local service, send an event, read acceptance correctly, and explain why replay keeps the same ID. Failure recovery, queue partitioning, and production operation belong to the how-to, spec, and runbook.