Skip to content

feat(api)!: answer like api.New on the default instance - #71

Merged
josuegiron merged 1 commit into
masterfrom
feat/default-instance-wire
Nov 21, 2026
Merged

josuegiron merged 1 commit into
masterfrom
feat/default-instance-wire

Conversation

@josuegiron

Copy link
Copy Markdown
Member

Scope

PR 1 of 2 (stack: this PR → master; PR 2 feat/default-instance-slog targets this branch). Owner decision 2026-11-21: in v1.0.0 the default instance (requests without an api.New instance in the context) behaves like api.New() with its defaults.

This PR: the wire behavior of the default instance. Logging through slog.Default is PR 2. No tag; merge bottom-up (this one first, then retarget PR 2 to master).

Reason for the split: the full change is ~1,760 changed lines (PR-02 limit 1,000). Each PR passes gofmt, vet, -race and govulncheck on its own base.

Changes

  • One code path: the fromNew forks for codes, token echo, RequestHeaderSession, the body limit and problem mode are removed. getSecurityToken is deleted.
  • Codes: the zero ResponseFormatter sends codes as declared (declaredCodes → lowercaseCodes). WithLowercaseCodes is the only way back.
  • No token echo: Success/Error/Warning/Informative.Write no longer fill SecurityToken from the request. RequestHeaderSession no longer copies the header.
  • Body limit: the default instance bounds bodies at 10 MiB at the library's read points (ProcessRequest, RequestBody, ProcessBody, ProcessEncryptedBody, UnmarshalBody). Any *http.MaxBytesError answers 413 E002. A handler that reads r.Body itself is not bounded outside an instance.
  • Problem mode: SetResponseMode(ResponseModeProblem) is accepted.
  • Docs:
    • ADR 0001: Amendment 1 (owner, dated), with superseded statements marked.
    • Migration guide: Step 1 "what changes without code changes" becomes the main upgrade path.
    • README and docs/legacy.md updated.

Breaking (default-instance users)

  • Codes are sent as declared (E001, TSK-001).
  • No request token echo, in bodies or in the RequestHeaderSession header.
  • Bodies are capped at 10 MiB; over the limit, the answer is 413 instead of 400.
  • SetResponseMode(ResponseModeProblem) now writes problem details.

Stay on v0.11.x to keep v0 behavior.

Tests

  • New default_instance_test.go:
    • TestDefaultInstanceAnswersLikeNew: status, headers and body equal New().Handler, apart from event IDs (14 cases);
    • envelope request mode;
    • declared codes, no echo, no session copy;
    • 413 at every read point, and a body exactly at the limit accepted;
    • problem mode.
  • New TestInstanceLimitAboveTheDefaultIsNotCapped (a larger WithMaxBodyBytes is not capped at 10 MiB).
  • Tests that pinned v0 codes, echo or limits now pin v1. The v0 golden log test is kept here: logging is unchanged until PR 2.

Verification

  • gofmt -l .: empty.
  • go vet ./...: OK.
  • go test -race ./...: all packages OK.
  • govulncheck ./...: no vulnerabilities.

Decisions and open owner questions: questions-for-owner, "Default instance = New (2026-11-21)", Q52 and Q53.

🤖 Generated with Claude Code

Owner decision (2026-11-21): in v1.0.0 the default instance (requests
without an api.New instance in context) behaves like api.New() with its
defaults. This change covers the wire behavior; logging follows in the
next change of the stack. The fromNew forks for codes, token echo,
RequestHeaderSession, the body limit and problem mode are gone; one code
path serves both. ADR 0001 gets Amendment 1; README and the migration
guide make "what changes without code changes" the main upgrade path.

BREAKING CHANGE: for programs that use the package-level API without
api.New (the default instance):
- response codes are sent as declared (E001, E300, TSK-001), not
  lowercased; there is no package-level switch back, only
  api.New(api.WithLowercaseCodes());
- the request token (SecurityToken header, Authorization: Bearer,
  envelope header.token) is no longer echoed in response bodies;
- RequestHeaderSession no longer copies the SecurityToken request
  header into the response header;
- ProcessRequest, RequestBody, ProcessBody, ProcessEncryptedBody and
  UnmarshalBody read at most 10 MiB; a larger body, or any
  *http.MaxBytesError, answers 413 E002 "Request content too large"
  (v0.11.0: no limit, 400 for a service-installed limit);
- SetResponseMode(ResponseModeProblem) is accepted and writes RFC 9457
  problem details (v0.11.0 fell back to envelope);
- the zero ResponseFormatter sends codes as declared.
Stay on v0.11.x to keep v0 behavior.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@josuegiron
josuegiron merged commit d324dcd into master Nov 21, 2026
2 checks passed
@josuegiron
josuegiron deleted the feat/default-instance-wire branch November 21, 2026 18:26
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