Tutorial

AlphaVerification Required

Concordia TSDB and Gateway alpha tutorial.

Append and query local Concordia Time Series samples, then inspect Gateway readiness blockers and the protected alpha write route without expanding the claim beyond local evidence.

Current availability

Private Beta. Public beta is scheduled for December 7, 2026.

Result

You will start the local concordia-tsdb-bin shell, append samples, query recent values newest-first, prove --retention-max-records 2, restart the Gateway from blocked mode into an alpha-ready local configuration, and send one protected PUT /v1/cache/{key} write that remains diagnostic alpha evidence.

Maturity Status

Time Series Local Shell

Alpha

The TSDB workflow uses local memory only. Health reports durability:none, replication:none, and projection_freshness:unavailable.

Gateway Alpha Route

Verification Required

The Gateway write path is protected by readiness blockers and local bearer-token admission. The accepted response is diagnostic only and reports committed:false plus visible:false.

Prerequisites

Required tools

Required

cargo --version for the Rust toolchain.
curl --version for HTTP requests.
A local Service.Concordia source checkout.
Two terminals: one for a running service and one for requests.

Time Series setup

Required

Run concordia-tsdb-bin from the Service.Concordia workspace root.
Use a free loopback bind address. This tutorial uses 127.0.0.1:9201.
Protected TSDB routes use Authorization: Bearer local-tsdb-token.
--retention-max-records 2 keeps the memory-only retention behavior easy to see.

Gateway setup

Required

Run concordia-gateway-bin from the Service.Concordia workspace root.
Use a free loopback bind address. This tutorial uses 127.0.0.1:9301.
Protected Gateway writes use Authorization: Bearer local-gateway-token and Idempotency-Key.
The alpha-ready write path needs --write-mode alpha-enabled, --owner-transport in-process, local fixture metadata, retry budget, and tenant quota.

Optional helpers

Optional

jq can make response inspection easier, but every command below works with shell and curl only.
Support/Validate-TSDB-Local.sh and Support/Validate-Gateway-Alpha-Route-Smoke.sh validate the source project smoke paths separately.

See local prerequisites for the shared tool baseline.

Start The TSDB Service

Use one terminal for the TSDB service and a second terminal for the workflow commands.

Run Concordia TSDB locally

Service terminal

cd /path/to/Service.Concordia
cargo run -p concordia-tsdb-bin -- \
  --bind 127.0.0.1:9201 \
  --retention-max-records 2

Expected output

concordia-tsdb listening on http://127.0.0.1:9201

Keep this terminal open while you run the TSDB workflow commands.

Complete The TSDB Workflow

Configure TSDB values

Copy/paste

Run these values in the workflow terminal while the TSDB service terminal stays open.

export CONCORDIA_TSDB_ENDPOINT=http://127.0.0.1:9201
export CONCORDIA_TSDB_TOKEN=local-tsdb-token

Expected output

The workflow terminal now points at the local TSDB shell, and protected routes use the local bearer token.

Check TSDB health

Copy/paste

Confirm the product binary is listening and reports the local memory-only storage model.

curl -s -i "$CONCORDIA_TSDB_ENDPOINT/health"

Expected output

HTTP/1.1 200 OK

{"status":"ok","product":"concordia-tsdb","storage":"local_memory_only","durability":"none","replication":"none","projection_freshness":"unavailable","retention_max_records":2}

Check protected TSDB admission

Copy/paste

Call sample append without authorization before writing data so the local policy boundary is visible.

curl -s -i -X POST "$CONCORDIA_TSDB_ENDPOINT/v1/samples" \
  -H "content-type: application/json" \
  --data '{"tenant_id":"tenant-a","dataset_id":"metrics","series_name":"http.latency","tags":{"host":"api-1","region":"us-east"},"timestamp_micros":100,"value":42.5}'

Expected output

HTTP/1.1 401 Unauthorized

{"error":"missing_authorization"}

Append the first sample

Copy/paste

Append one value to the local in-memory series. The accepted response is not a distributed or persistent write claim.

curl -s -i -X POST "$CONCORDIA_TSDB_ENDPOINT/v1/samples" \
  -H "authorization: Bearer $CONCORDIA_TSDB_TOKEN" \
  -H "content-type: application/json" \
  --data '{"tenant_id":"tenant-a","dataset_id":"metrics","series_name":"http.latency","tags":{"host":"api-1","region":"us-east"},"timestamp_micros":100,"value":42.5}'

Expected output

HTTP/1.1 201 Created

{"outcome":"accepted","timestamp_micros":100,"retained_record_count":1,"durability":"local_memory_only","replication":"none"}

Append a newer sample

Copy/paste

Append a second value to the same series so the recent query can prove newest-first ordering.

curl -s -i -X POST "$CONCORDIA_TSDB_ENDPOINT/v1/samples" \
  -H "authorization: Bearer $CONCORDIA_TSDB_TOKEN" \
  -H "content-type: application/json" \
  --data '{"tenant_id":"tenant-a","dataset_id":"metrics","series_name":"http.latency","tags":{"host":"api-1","region":"us-east"},"timestamp_micros":200,"value":45.25}'

Expected output

HTTP/1.1 201 Created

{"outcome":"accepted","timestamp_micros":200,"retained_record_count":2,"durability":"local_memory_only","replication":"none"}

Query recent samples

Copy/paste

Query the same series with the tags in a different order. The identity still matches, and records come back newest first.

curl -s -i -X POST "$CONCORDIA_TSDB_ENDPOINT/v1/query/recent" \
  -H "authorization: Bearer $CONCORDIA_TSDB_TOKEN" \
  -H "content-type: application/json" \
  --data '{"tenant_id":"tenant-a","dataset_id":"metrics","series_name":"http.latency","tags":{"region":"us-east","host":"api-1"},"limit":10}'

Expected output

HTTP/1.1 200 OK

{
  "series_found":true,
  "records":[
    {"series":{"tenant_id":"tenant-a","dataset_id":"metrics","series_name":"http.latency","tags":{"host":"api-1","region":"us-east"}},"timestamp_micros":200,"value":45.25},
    {"series":{"tenant_id":"tenant-a","dataset_id":"metrics","series_name":"http.latency","tags":{"host":"api-1","region":"us-east"}},"timestamp_micros":100,"value":42.5}
  ],
  "durability":"local_memory_only",
  "replication":"none"
}

Prove local retention

Copy/paste

Append one more sample. With --retention-max-records 2, the in-memory store keeps only the newest two records for this series.

curl -s -i -X POST "$CONCORDIA_TSDB_ENDPOINT/v1/samples" \
  -H "authorization: Bearer $CONCORDIA_TSDB_TOKEN" \
  -H "content-type: application/json" \
  --data '{"tenant_id":"tenant-a","dataset_id":"metrics","series_name":"http.latency","tags":{"host":"api-1","region":"us-east"},"timestamp_micros":300,"value":47.0}'

curl -s -i -X POST "$CONCORDIA_TSDB_ENDPOINT/v1/query/recent" \
  -H "authorization: Bearer $CONCORDIA_TSDB_TOKEN" \
  -H "content-type: application/json" \
  --data '{"tenant_id":"tenant-a","dataset_id":"metrics","series_name":"http.latency","tags":{"host":"api-1","region":"us-east"},"limit":10}'

Expected output

The append returns retained_record_count:2.

The recent query returns timestamps 300 and 200, in that order. Timestamp 100 is no longer retained by this local process.

Start Gateway Blocked Mode

Stop TSDB or keep it running on its own port. Use the service terminal for Gateway, starting with the default fail-closed posture.

Run Concordia Gateway locally

Service terminal

cd /path/to/Service.Concordia
cargo run -p concordia-gateway-bin -- \
  --bind 127.0.0.1:9301

Expected output

concordia-gateway listening on http://127.0.0.1:9301

Keep this terminal open for the blocked-readiness checks.

Check Gateway Blockers

Configure Gateway values

Copy/paste

Set request values for the Gateway alpha route. The body idempotency key must match the Idempotency-Key header.

export CONCORDIA_GATEWAY_ENDPOINT=http://127.0.0.1:9301
export CONCORDIA_GATEWAY_TOKEN=local-gateway-token
export CONCORDIA_GATEWAY_KEY=customer:42
export CONCORDIA_GATEWAY_COMMAND=docs-026-gateway-command-1

Expected output

The workflow terminal now points at the local Gateway shell and has one tutorial command ID.

Check blocked readiness

Copy/paste

Start with the fail-closed configuration to see the readiness blockers before enabling the alpha write path.

curl -s -i "$CONCORDIA_GATEWAY_ENDPOINT/health"

Expected output

HTTP/1.1 200 OK

{
  "status":"ok",
  "product":"concordia-gateway",
  "writes_enabled":false,
  "alpha_write_ready":false,
  "alpha_write_blockers":[
    {"code":"write_mode_disabled","detail_code":null},
    {"code":"metadata_source_disabled","detail_code":null},
    {"code":"owner_transport_disabled","detail_code":null},
    {"code":"retry_budget_disabled","detail_code":null},
    {"code":"tenant_quota_disabled","detail_code":null}
  ]
}

Check blocked write behavior

Copy/paste

The protected alpha route checks admission and idempotency first, then reports the first readiness blocker before mutation.

curl -s -i -X PUT "$CONCORDIA_GATEWAY_ENDPOINT/v1/cache/$CONCORDIA_GATEWAY_KEY" \
  -H "authorization: Bearer $CONCORDIA_GATEWAY_TOKEN" \
  -H "idempotency-key: docs-026-disabled-command" \
  -H "content-type: application/json" \
  --data '{"tenant_id":"tenant-a","dataset_id":"cache","key":"customer:42","value":"value-42","idempotency_key":"docs-026-disabled-command","consistency_target":"accepted"}'

Expected output

HTTP/1.1 503 Service Unavailable

{
  "error_code":"unavailable",
  "reason_code":"write_mode_disabled",
  "consistency_labels":{"accepted":false,"durable":false,"committed":false,"visible":false,"rejected":true,"diagnostic_only":false}
}

Restart Gateway Alpha-Ready

Press Ctrl-C in the Gateway service terminal, then restart with the local fixture and in-process owner runtime.

Run Gateway with alpha write readiness

Service terminal

cd /path/to/Service.Concordia
cargo run -p concordia-gateway-bin -- \
  --bind 127.0.0.1:9301 \
  --write-mode alpha-enabled \
  --owner-transport in-process \
  --admission-token local-gateway-token \
  --metadata-fixture fixtures/metadata/placement-alpha-v2.txt \
  --metadata-fallback fail-closed \
  --retry-budget 1:1:250 \
  --tenant-quota-max-in-flight 64 \
  --tenant-quota-retry-after-millis 250

Expected output

concordia-gateway listening on http://127.0.0.1:9301

Keep this terminal open while you run the alpha-ready Gateway workflow.

Complete The Gateway Alpha Workflow

Check alpha-ready health

Copy/paste

After restarting with the alpha-ready command, health should show that the local in-process owner path is ready.

curl -s -i "$CONCORDIA_GATEWAY_ENDPOINT/health"

Expected output

HTTP/1.1 200 OK

{"status":"ok","product":"concordia-gateway","writes_enabled":true,"alpha_write_ready":true,"alpha_write_blockers":[]}

Inspect placement metadata

Copy/paste

The local fixture publishes topology epoch 2 and metadata version 2 for the cache dataset.

curl -s -i "$CONCORDIA_GATEWAY_ENDPOINT/placement/cache"

Expected output

HTTP/1.1 200 OK

Response fields include:

{
  "has_current_snapshot":true,
  "topology_epoch":2,
  "metadata_version":2,
  "last_metadata_refresh_status":"published",
  "metadata_fallback_decision":"not_needed",
  "routing_enabled":true,
  "write_forwarding_enabled":true
}

Check write admission

Copy/paste

Call the alpha write route without the bearer token so the local admission boundary remains visible.

curl -s -i -X PUT "$CONCORDIA_GATEWAY_ENDPOINT/v1/cache/$CONCORDIA_GATEWAY_KEY" \
  -H "idempotency-key: docs-026-missing-auth-command" \
  -H "content-type: application/json" \
  --data '{"tenant_id":"tenant-a","dataset_id":"cache","key":"customer:42","value":"value-42","idempotency_key":"docs-026-missing-auth-command","consistency_target":"accepted"}'

Expected output

HTTP/1.1 401 Unauthorized

{
  "error_code":"unauthorized",
  "reason_code":"missing_authorization",
  "consistency_labels":{"accepted":false,"durable":false,"committed":false,"visible":false,"rejected":true,"diagnostic_only":false}
}

Check idempotency validation

Copy/paste

Send the bearer token but omit the Idempotency-Key header. The route rejects the request before parsing the write body as a mutation.

curl -s -i -X PUT "$CONCORDIA_GATEWAY_ENDPOINT/v1/cache/$CONCORDIA_GATEWAY_KEY" \
  -H "authorization: Bearer $CONCORDIA_GATEWAY_TOKEN" \
  -H "content-type: application/json" \
  --data '{"tenant_id":"tenant-a","dataset_id":"cache","key":"customer:42","value":"value-42","idempotency_key":"docs-026-missing-idempotency-command","consistency_target":"accepted"}'

Expected output

HTTP/1.1 400 Bad Request

{
  "error_code":"malformed_request",
  "reason_code":"missing_idempotency_key",
  "consistency_labels":{"accepted":false,"durable":false,"committed":false,"visible":false,"rejected":true,"diagnostic_only":false}
}

Write through the alpha route

Copy/paste

Send one accepted-target write through the local in-process owner runtime. Treat the response as diagnostic alpha evidence, not as a committed or visible user-read guarantee.

curl -s -i -X PUT "$CONCORDIA_GATEWAY_ENDPOINT/v1/cache/$CONCORDIA_GATEWAY_KEY" \
  -H "authorization: Bearer $CONCORDIA_GATEWAY_TOKEN" \
  -H "idempotency-key: $CONCORDIA_GATEWAY_COMMAND" \
  -H "content-type: application/json" \
  --data '{"tenant_id":"tenant-a","dataset_id":"cache","key":"customer:42","value":"value-42","idempotency_key":"docs-026-gateway-command-1","consistency_target":"accepted"}'

Expected output

HTTP/1.1 202 Accepted

Response fields include:

{
  "outcome":"accepted",
  "consistency_target":"accepted",
  "consistency_labels":{"accepted":true,"durable":true,"committed":false,"visible":false,"rejected":false,"diagnostic_only":true},
  "idempotency_key":"docs-026-gateway-command-1",
  "record_hash":"<64 lowercase hex characters>",
  "log_index":1,
  "topology":{"topology_epoch":2,"leader_term":2,"metadata_version":2,"placement_hash_version":1}
}

Verify Success

The tutorial is successful when TSDB health reports local_memory_only, authorized sample appends return outcome:"accepted", recent query returns timestamps 300 and 200, Gateway blocked mode reports readiness blockers including write_mode_disabled, alpha-ready health reports writes_enabled:true, and the final Gateway write returns 202 Accepted with diagnostic_only:true, committed:false, and visible:false.

Clean Up

Stop the TSDB service

Copy/paste

Stop Concordia TSDB with Ctrl-C in the service terminal. The accepted samples are process-local memory only.

# Press Ctrl-C in the terminal running concordia-tsdb-bin.

Expected output

The local concordia-tsdb process exits, and the tutorial samples are gone.

Stop the Gateway service

Copy/paste

Stop Concordia Gateway with Ctrl-C in the service terminal. The alpha write used a local in-process owner runtime.

# Press Ctrl-C in the terminal running concordia-gateway-bin.

Expected output

The local concordia-gateway process exits.

Troubleshooting

Common first-run failures
Symptom	How to recognize it	Likely cause	Fix
Service does not start	`cargo run` reports that the address is already in use or cannot bind.	Another local process is using `127.0.0.1:9201` or `127.0.0.1:9301`.	Choose a different loopback port with `--bind` and update the matching endpoint environment variable.
TSDB protected route returns `missing_authorization`	The response status is `401 Unauthorized` and the JSON error is `missing_authorization`.	The authorization header was omitted.	Send `authorization: Bearer local-tsdb-token` on `/v1/samples` and `/v1/query/recent`.
TSDB recent query returns `series_found:false`	The query succeeds with `200 OK`, but the `records` array is empty.	The tenant, dataset, series name, or tags do not match the appended samples.	Reuse the exact tutorial identity: tenant `tenant-a`, dataset `metrics`, series `http.latency`, and tags `host:api-1` plus `region:us-east`.
Gateway health stays blocked	`alpha_write_ready` is `false`, or `alpha_write_blockers` is not empty after restart.	One of the alpha-ready flags is missing, or the metadata fixture path is not available from the Service.Concordia workspace root.	Restart the Gateway command with `--write-mode alpha-enabled`, `--owner-transport in-process`, `--metadata-fixture fixtures/metadata/placement-alpha-v2.txt`, `--retry-budget 1:1:250`, and `--tenant-quota-max-in-flight 64`.
Gateway write returns `missing_idempotency_key`	The response status is `400 Bad Request` and `reason_code` is `missing_idempotency_key`.	The `Idempotency-Key` header was omitted.	Send the header and keep it equal to the optional body `idempotency_key` value.
Gateway write returns `conflicting_idempotency_key`	The response status is `400 Bad Request` and `reason_code` is `conflicting_idempotency_key`.	The `Idempotency-Key` header and request-body `idempotency_key` field differ.	Set both values to `docs-026-gateway-command-1`, or omit the body field and keep the header.
Gateway write returns `write_mode_disabled`	The response status is `503 Service Unavailable` and `reason_code` is `write_mode_disabled`.	The Gateway is still running with default write mode disabled, or the wrong local process is listening on the endpoint.	Stop the blocked-mode process and restart with the documented alpha-ready command.

Evidence

Source-backed tutorial checks
Workflow step	Evidence	Status
TSDB startup and route contract	Service.Concordia/bins/concordia-tsdb/src/main.rs and bins/concordia-tsdb/src/http.rs	Source-backed; local memory-only behavior
TSDB append, recent query, and retention	Service.Concordia/crates/concordia-tsdb/src/store.rs and bins/concordia-tsdb/src/http.rs tests	Source-backed; records are process-local
Gateway readiness blockers	Service.Concordia/README.md, bins/concordia-gateway/src/startup.rs, and bins/concordia-gateway/src/http/routes.rs	Source-backed; alpha route stays fail-closed until blockers clear
Gateway alpha write behavior	Service.Concordia/Support/Validate-Gateway-Alpha-Route-Smoke.sh and bins/concordia-gateway/src/http/tests.rs	Source-backed; in-process owner runtime only
Metadata fixture	Service.Concordia/fixtures/metadata/placement-alpha-v2.txt	Source-backed; topology epoch 2 and metadata version 2

Limits

TSDB Is Memory Only

Accepted TSDB samples live in the current concordia-tsdb-bin process. Restarting the process removes tutorial samples, and the response states durability:none and replication:none.

Local Bearer Tokens

TSDB and Gateway protected routes use fixed local bearer tokens. Production identity-provider behavior, JWT signature verification, and key-source loading are outside this tutorial.

Gateway Route Is Alpha

The Gateway write path must pass readiness blockers before mutation. The accepted response is diagnostic alpha evidence with committed:false, visible:false, and diagnostic_only:true.

Fixture-Bound Placement

Gateway placement comes from fixtures/metadata/placement-alpha-v2.txt. It does not prove external metadata watches, TCP owner forwarding, quorum commit, cross-node routing, or restart recovery.

Next Steps

Available now
Run the Cache quickstart
Exercise local Cache put, get, count, TTL, stale-version behavior, placement diagnostics, and persistence boundaries.
Available now
Review Concordia evidence
Use the evidence index before strengthening Concordia Cache, TSDB, Gateway, Storage, active compatibility, or workflow claims.
Available now
Read tutorial prerequisites
Check the shared local tool baseline and product-specific setup expectations for first-success tutorials.
Available now
Read runtime surface reference
Separate Cache HTTP, Gateway alpha, Storage validation, active service, and protocol fixture surfaces.
Available: DOCS-061
Use local curl examples
Reuse tested Cache, TSDB, Gateway alpha, and active compatibility curl snippets with local-only boundaries.
Available: DOCS-053
Use validation runbooks
Triage TSDB local checks, Gateway readiness blockers, diagnostic accepted writes, Storage boundaries, and evidence handoff.
Available: DOCS-041
Map runtime boundaries
Compare local, alpha, validation, fixture, future, and verification-required Concordia runtime surfaces.