Adopt StructuredError bubbling standard on governance surfaces#53
Merged
Conversation
…I edge
Add a global Oak error middleware that logs any thrown error with its full
cause chain plus correlation ids (requestId/traceId) and translates it to the
structured { status, code, message, details } ErrorResponse via the existing
PIPE_APIError edge pipeline — mirroring provider-platform.
- PlatformError now preserves the wrapped original as the native Error cause
so the chain flows into logs/OTel (logger flattenCauses); the redacted api
projection is all that reaches the client.
- Add per-domain PlatformError subclasses (auth challenge/signature, escrow,
channel-state) and shared HTTP request errors (validation, not-found,
conflict, forbidden, invalid-body); replace raw throw new Error and ad-hoc
{ message } handler bodies across the governance routes.
- jwtMiddleware and council-auth service now throw structured errors instead
of hand-writing responses.
- Tests exercise the structured responses via a runHandler/runMiddleware edge
helper; add error-catalog and logger cause-chain unit tests.
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
1 participant
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.
What
Adopts the StructuredError bubbling standard on council-platform's governance surfaces, mirroring the already-merged provider-platform implementation. Errors are wrapped with context (preserving the original as the cause chain into logs/OTel) and translated to a structured
{ status, code, message, details }response only at the API edge.Why
council-platform already had the
PlatformErrorclass, theErrorResponseschema, and thePIPE_APIErroredge pipeline — but only the JWT middleware used them. Every route handler instead did ad-hoctry/catch → ctx.response.body = { message }(no code/status/details), and services threw rawnew Error(...). This brings the whole governance path onto the standard so council-console can consume machine-readable error codes.Changes
Edge boundary
errorMiddleware(wired outermost inmain.ts): catches anything thrown downstream, logs it with the full cause chain + correlation ids (requestId/traceId), and translates it via the existingPIPE_APIErrorpipeline. Handlers/services nowthrow; the redactedapiprojection is all that reaches the client.PlatformErrornow preserves the wrapped original as the nativeErrorcause, and the logger flattens the cause chain (msg <- cause <- cause) and renders correlation ids.503 Service Unavailableto the allowed error-status set (dependency-unavailable, e.g. channel on-chain read).Error catalog (wrap-with-cause)
PlatformErrorsubclasses: auth challenge/signature (COUNCIL_AUTH_*), escrow (ESCROW_*), channel-state (CHANNEL_*).HTTP_REQ_*: validation, not-found, conflict, forbidden, invalid-body, id-required) and council-specific (HTTP_COUNCIL_*: missing-council-id, council-not-found).throw new Error(...)and ad-hoc{ message }bodies across auth, providers, channels, jurisdictions, metadata, escrow, join-requests, sign, and public join-request.jwtMiddlewareand the council-auth service now throw structured errors.Tests
runHandler/runMiddlewareedge helper so error-path tests assert the structured body; added error-catalog and logger cause-chain unit tests.deno fmt/lint/check src/main.tsgreen; 65 unit + 185 integration passing.Note:
StructuredErroris not exported by moonlight-sdk 0.11.1, so this uses council-platform's existing localPlatformError/ErrorResponse(matching provider-platform's shape).Pairs with the council-console consumer PR.