Skip to content

Release 1.5.0: FRS-1 specification, Python/Go/Rust SDKs and the sidecar gateway - #12

Merged
umudhasanli merged 1 commit into
mainfrom
feat/frs1-spec-sdks-gateway
Aug 6, 2026
Merged

umudhasanli merged 1 commit into
mainfrom
feat/frs1-spec-sdks-gateway

Conversation

@umudhasanli

Copy link
Copy Markdown
Collaborator

What this adds

FRS-1, a portable detector specification. spec/SPEC.md describes how a
detector pack is written and executed — the pattern subset, the scan algorithm,
overlap resolution, confidence, replacement modes, keyed transforms, vault
semantics and failure behaviour — precisely enough that independent engines
produce identical output. It ships with spec/detectors.json, its JSON schema,
and a 121-case conformance corpus that every engine's suite runs.

The pattern subset forbids every construct whose meaning differs across
JavaScript, Python, Go and Rust — lookaround, backreferences, \b \d \w \s,
\p{…}, inline flags and anchors — replacing them with explicit boundary,
reject, named validators and the {{ANY}} / {{L}} tokens. It is RE2-safe by
construction, so a pack cannot introduce catastrophic backtracking into a host.

Python, Go and Rust SDKs. Each implements FRS-1 against the shared corpus,
with the engine, vaults, sessions, and the logging and HTTP integrations native
to its ecosystem — a logging filter and formatter for Python, an
slog.Handler and http.RoundTripper for Go, serde_json::Value traversal for
Rust.

The sidecar gateway. A reverse proxy that redacts request bodies on the way
out and restores the originals on the way back, so an application integrates by
changing one base URL. Streamed responses are restored incrementally. It also
serves /v1/redact, /v1/scan, /v1/detectors and server-side /v1/sessions
for languages without a native engine, plus health and Prometheus endpoints, and
ships a multi-stage non-root Docker image.

Library additions. flare-redact/pack loads an FRS-1 document as ordinary
detectors, RedactOptions.detectors replaces the built-in set, and boundary /
reject give custom detectors portable spellings for \b and a trailing
negative lookahead.

Verification

Run locally on macOS arm64 against freshly installed Go 1.25.5 and Rust 1.97.1:

Node 341 tests
Python 87 tests (3.9)
Go 18 tests, go vet clean
Rust 19 tests, clippy --all-targets -D warnings clean
Spec spec:sync --check, conformance build, Bun/Deno runtime smoke
Packaging npm ci, npm audit, npm pack, clean install of the npm tarball and the Python wheel
Examples all three smokes
Gateway the Docker runtime layer assembled from the Dockerfile's exact COPY set starts and answers /healthz, /v1/detectors, /v1/redact and /metrics

The real docker build is left to the gateway-image job in this PR's CI; it
was not run locally.

Notes for review

Three fixes in here are worth a second look:

  • The gateway reserved the whole /v1/ prefix for its own API, which meant it
    404'd every vendor path it exists to proxy — /v1/chat/completions,
    /v1/models, /v1/messages. Only the eight control paths shadow the upstream
    now; a regression test covers it.
  • An oversized body reset the socket instead of delivering the 413, so a caller
    could not tell a refusal from a network failure.
  • The conformance corpus trips GitHub push protection by design: it contains
    synthetic strings shaped like real provider credentials, which is the point.
    Six detections were reviewed and allowed as test data.

…ar gateway

Add FRS-1 (spec/SPEC.md), a normative description of detector packs and the
scan algorithm precise enough that independent engines produce identical
output, together with spec/detectors.json, its JSON schema, and a 121-case
conformance corpus that every engine's test suite runs.

Add Python, Go and Rust SDKs implementing FRS-1 against that corpus, each with
the engine, vaults, sessions and the logging and HTTP integrations native to
its ecosystem.

Add the sidecar gateway and its Docker image: a reverse proxy that redacts
request bodies on the way out and restores the originals on the way back, so an
application integrates by changing one base URL. It also serves /v1/redact,
/v1/scan, /v1/detectors and server-side /v1/sessions for languages without a
native engine, plus health and Prometheus endpoints.

Add flare-redact/pack so a pack loads into the JavaScript engine as ordinary
detectors, RedactOptions.detectors to replace the built-in set, and the
portable `boundary` and `reject` detector fields.

Verified: 341 Node tests, 87 Python, 18 Go, 19 Rust, go vet, clippy -D warnings,
the spec drift check, all three example smokes, npm pack and a clean install of
both the npm tarball and the Python wheel.
@umudhasanli
umudhasanli merged commit 9ebde61 into main Aug 6, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant