Optional external Test API¶
This source service supports the limited external Test recipe below with unmodified SignalFlag SDK 1.8.0. Projects, branches and tenant membership are configured before the SDK runs. A completed SDK Test reports producer metadata; it does not qualify a robot or launch a native workload.
Run the source fixture¶
From a checkout, with Docker, its default Buildx builder, Git, Bash and Python 3:
API_FIXTURE_ENGINE=docker api/test/run-fixture.sh
The driver builds the API, unchanged installed SDK and custody inputs from
pinned sources. It creates disposable local
PostgreSQL 18.6, Keycloak 26.8 and SeaweedFS 4.29 services, generates private
fixture credentials, and removes its owned resources. It is a finite test,
not a long-running service deployment. A refused check or
unverified cleanup returns a nonzero exit. Safe reports and original custody
proofs are retained under artifacts/api-ci-safe/.
The fixture exercises both tenants, default configuration sync, all six REST operations, JSONL/PNG/empty PUTs, authorization refusals, lost configuration, registration and close responses, eight concurrent closes and two-upload recovery after a refused close and API restart. It verifies exact VersionId payloads and preserves the first committed proof checkpoint. SeaweedFS is a local S3-compatible protocol fixture; this is not AWS qualification.
Use an installed SDK¶
Obtain a real token from the configured issuer and authorize its subject through tenant/project membership. The client receives that token explicitly; this recipe does not use the SDK’s Auth0 helpers. Install the client in your own Python environment with the pinned dependency lock.
from pathlib import Path
import httpx
from signalflag.sdk.batch import Batch
from signalflag.sdk.client import AuthenticatedClient
from signalflag.sdk.test import LogType, Test
token = Path("/run/secrets/sdk-token").read_text().strip()
client = AuthenticatedClient(
base_url="http://api:3000",
token=token,
timeout=httpx.Timeout(90.0),
)
config = Path(".resim/metrics/config.resim.yml")
config.parent.mkdir(parents=True, exist_ok=True)
config.write_text("version: 1\ntopics:\n motion:\n schema:\n speed: float\n")
Path("empty.log").write_bytes(b"")
with Batch(
client=client,
project_id="YOUR_EXISTING_PROJECT_UUID",
branch="main",
name="External Test",
) as batch:
with Test(client=client, batch=batch, name="opaque external test") as run:
run.emit("motion", {"speed": 1}, timestamp=1_791_000_000_000_000_000)
run.attach_log("attachment.png", log_type=LogType.OTHER_LOG, wait=True)
run.attach_log("empty.log", log_type=LogType.OTHER_LOG, wait=True)
The example uses the fixture’s container-network API address. Replace the
endpoint and project UUID with configured values, and supply the PNG file.
Both the API and returned S3 upload URL must be reachable from the client.
The Test context flushes and uploads the SDK’s original emissions JSONL.
The default config path synchronizes this file before the REST journey.
Optional immediate .liquid files under .resim/metrics/templates are stored
as bytes; a missing template directory sends an empty list. Passing
metrics_config_path=None still supports the recipe without configuration sync.
Do not add project_name, system, test-suite or metrics-set options.
The service implements this bounded surface:
POST /graphql (UpdateMetricsConfig only)
GET /projects/{projectID}/branches?name=main
POST /projects/{projectID}/batches/light
POST /projects/{projectID}/batches/{batchID}/jobs
POST /projects/{projectID}/batches/{batchID}/jobs/{jobID}/logs
POST /projects/{projectID}/batches/{batchID}/jobs/{jobID}/close
POST /projects/{projectID}/batches/{batchID}/close
Log registration returns the fixed server-owned object URL and required PUT headers. Checksum, size, media type and exact VersionId must match before custody. An identical pending, unbound registration can renew its URL after a refused close. A close retry must preserve the original producer claim. Registration identity and close recovery do not deduplicate batch/job creation for the unchanged SDK: it supplies no per-creation key. Own clients can use the optional header below.
Retry batch and job creation¶
Own clients may send Idempotency-Key: "CLIENT_GENERATED_UUID" with either
creation POST. Use a new key for each intended batch or job and preserve it
across retries, including a lost HTTP response. The value is one quoted ASCII
Structured Fields string of 1–256 characters, without parameters; malformed
headers return 400 before creation. Parsing uses
structured-headers. The header
name follows the HTTPAPI draft,
not a published RFC; the behavior below is this service’s contract.
A committed identical request returns the original 201 creation response.
The batch key is scoped to tenant, project and authenticated principal; the
job key also includes its batch. Reusing a key with different creation fields
returns 409. Batch fingerprints include branch, optional name and version;
an omitted metricsSetName and null have the same meaning. JSON member order
does not change identity. A retry preserves the first batch’s configuration
snapshot even after the branch changes.
Concurrent requests settle through PostgreSQL transactions and unique indexes. A matching request waits for the competing transaction and returns its committed creation. If the bounded lock wait fails, retry the same key. Failed or rolled-back transactions do not claim a key. Keys are retained for the lifetime of their rows; there is no time-based expiry. A service/database restart preserves them. Authorization is checked again on every request.
The response describes the original creation, including after the batch or job closes. It is not a current-state query or a native verdict. Requests without a key retain the existing behavior and can create duplicates. The unchanged SDK does not add keys automatically.
Configuration snapshots¶
UpdateMetricsConfig accepts projectId: String!, config: String!,
templateFiles: [MetricsTemplate!]! and branch: String. Each template contains
name and base64 contents. This recipe requires an existing project and branch.
Successful acknowledgement follows the SQL commit; GraphQL errors remain errors
to the SDK. Multiple fields use standard GraphQL serial mutation semantics:
a refused later field does not roll back an earlier committed field.
Canonical base64 is bounded before decoding: configuration up to 256 KiB, at most 32 templates of up to 64 KiB each, and 512 KiB combined decoded bytes. Template names are unique basenames. A single configuration file preserves its original bytes; multiple paths upload the YAML merged by the unchanged SDK. The server stores configuration and template bytes without executing Liquid or evaluating metrics. The SDK may validate emissions locally.
A batch pins the current branch snapshot atomically. Later updates preserve
that batch’s original snapshot. The SDK passes no snapshot identity between
sync and batch creation, so concurrent callers cannot assume a batch uses their
own last uploaded configuration. Repeating identical config bytes on the same
branch reuses the snapshot; sync_config itself does not retry a lost response.
The fixture’s retry is an explicit new call by the caller.
The SDK derives /graphql by replacing the first api. in the hostname with
bff. and dropping the base path. The example’s http://api:3000 stays on the
same host. A deployment using api.example must route the derived
bff.example hostname to this same optional service.
Service boundary¶
The entry point configures a separate Fastify process.
The base migration and
configuration migration use forced tenant/project
RLS. Apply the creation-key migration
before running this service; the application role must not own tables or reach privileged roles.
JWT verification fixes issuer, audience, RS256, subject, expiry and the
sdk-write role. Each SQL transaction sets the verified issuer/subject on the
same client.
Storage endpoints, bucket, object keys, byte limits, credential files, signing policy and worker commands belong to the server. The SDK cannot select an arbitrary URI or worker argv. Public core Jobs settle finite CLI processes; existing custody validators remain authoritative. Original proof blobs are committed per upload, and the job closes only when every upload is retained.
This optional package is private and has no published API image release. Released Python packages and host artifacts do not install the service. Only the configuration mutation is supplied through GraphQL; metrics evaluation, other vendor GraphQL operations, SDK Auth0 helpers, Web UI and product MCP are not supplied. Producer status is not a native verdict, opaque emissions are not converted into native observations, and the service does not use RunOwner. The source fixture does not establish deployment, AWS, full vendor-platform compatibility or an SLA.