Trusted-endpoint patterns + API key onboarding docs + drop cluster_b leftover#17
Closed
aural-psynapse wants to merge 5 commits into
Closed
Trusted-endpoint patterns + API key onboarding docs + drop cluster_b leftover#17aural-psynapse wants to merge 5 commits into
aural-psynapse wants to merge 5 commits into
Conversation
… registered URLs
A registered URL may now contain FastAPI/Express-style path placeholders so a
single entry covers a family of concrete URLs:
{name} - matches exactly one path segment (no '/').
e.g. https://api.example.com/customers/{id} matches
/customers/42 but NOT /customers/42/orders.
{name:path} - matches any subtree, including '/' separators.
e.g. https://api.example.com/customers/{rest:path} matches
both /customers/42 and /customers/42/orders.
Closes #14.
Why: customer-support-sdk-demo had to enumerate ~70 concrete URLs at startup
for templated routes (/customers/{id}). Runtime-generated ids (e.g. POST
/tickets returning a fresh id) couldn't be trusted until manually registered.
A single placeholder entry replaces the enumeration.
Implementation:
- Plain URLs without '{' keep exact-match semantics. No schema change. No
migration needed for existing rows. Existing exact-match tests unchanged.
- Pattern matching is auto-detected from URL content. Pattern compilation is
LRU-cached so repeated lookups don't recompile the regex.
- is_trusted_endpoint uses a two-phase lookup: exact match first (single
indexed query, fast path), then a pattern-only scan (LIKE '%{%' filter)
for rows containing placeholders. Plain registries see no perf regression.
- The snapshot tamper-check inside check_claim_endpoints_are_trusted honors
the same syntax — a payload built against a pattern entry verifies cleanly
on the receiver side.
Tests: 12 new (94 total). Ruff clean.
…G_ID New 'Getting PROVABLY_API_KEY and PROVABLY_ORG_ID' subsection under Configuration: 1. Sign up at app.provably.ai 2. Create an organisation (org id shown in the URL) 3. Left-side menu → Integrations → create one (generated key) Plus a pointer to provably.ai/docs for full product documentation. Closes the gap surfaced while users were trying to find where these values come from — the env-var table told them they were required but not where to source them.
…h-demo leftover) `default_cluster_b_url()` was extracted verbatim from the langgraph-demo monorepo (per CHANGELOG: 'Initial extraction from the langraph-demo monorepo'). Two problems: 1. The localhost:8082 default presumes a specific deployment shape (the original two-cluster demo); it is meaningless to a fresh SDK user. 2. 'cluster B' is internal terminology a user reading the SDK has no way to understand without context. Configuration of where YOUR receiver lives belongs in your application, not the SDK. `post_handoff` already takes the URL as a positional arg — drop the convenience helper, drop the env var, rename the arg from `cluster_b_url` to `receiver_url` for clarity. Breaking for callers that import `default_cluster_b_url` or pass `cluster_b_url=...` as a keyword arg. CHANGELOG entry added.
This was referenced May 6, 2026
SimoneBottoni
approved these changes
May 6, 2026
…helper # Conflicts: # CHANGELOG.md
Contributor
Author
|
Replaced by #19 — same content, linear history (the repo's rebase-merge requirement rejected the merge commit on this branch). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three small, self-contained changes bundled per request.
Closes #14.
1.
trusted_endpoints:{id}and{path:path}placeholders (commit)Registered URLs may now contain FastAPI/Express-style path placeholders so one entry covers a family of concrete URLs:
{name}/customers/{id}matches/customers/42but not/customers/42/orders{name:path}//customers/{rest:path}matches both abovePlain URLs without
{keep exact-match semantics — zero migration. Auto-detected from URL content;is_trusted_endpointdoes exact match first (fast path) and only scans pattern entries on a miss. The snapshot tamper-check incheck_claim_endpoints_are_trustedhonors the same syntax.12 new tests covering
{id}single-segment,{rest:path}subtree, multiple placeholders in one URL, the snapshot path, and the two-phase DB lookup.2. README: API key onboarding (commit)
Adds a short "Getting
PROVABLY_API_KEYandPROVABLY_ORG_ID" subsection under## Configuration:PROVABLY_API_KEY)Plus a link to provably.ai/docs. Closes the gap where the env-var table told users values were required but not where to source them.
3. Drop
default_cluster_b_url()+CLUSTER_B_URLenv var (commit)BREAKING for callers importing
default_cluster_b_urlor passingcluster_b_url=...as a keyword arg.These were extracted verbatim from the langgraph-demo monorepo. Two problems with keeping them in an SDK:
localhost:8082default presumes a specific deployment shape that has nothing to do with the SDK.Configuration of where YOUR verifier lives belongs in your application.
post_handoffalready takes the URL positionally — the helper and env var are dead weight. The positional arg is renamed fromcluster_b_urltoreceiver_urlfor clarity (positional callers unaffected).CHANGELOG entry covers the breakage.
Verification