Skip to content

docs: record exported API review and approval of E1-E6 - #6

Merged
ajbeck merged 2 commits into
claude/cleanup-line-breaks-b145a6from
claude/exported-api-review
Sep 27, 2026
Merged

ajbeck merged 2 commits into
claude/cleanup-line-breaks-b145a6from
claude/exported-api-review

Conversation

@ajbeck

@ajbeck ajbeck commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Adds decision 0026, a review of every exported identifier in edge, identity, authn, iamproof and authz. The review is based on Google's Go style guide (guide, decisions and best practices, read in full) and the primary sources it links. This PR changes no code: it records proposals for owner review, as AGENTS.md requires for public API decisions.

Stacked on #5.

Proposals (each separately approvable)

ID Recommendation Breaking
E1 Move ActionHeader out of the root edge package into a standard-library-only actionheader package. Today native HTTP consumers link the Lambda adapter just to select an action. Yes
E2 Rename the action sentinels so they match the module's adjective-first names (ErrInvalidEvent, ErrMissingCredentials) Yes
E3 Rename identity.WithCaller to identity.NewContext, pairing with FromContext. Every other With… function in the module is an option. Yes
E4 Typed constants for the InvocationError operation and limit names, which today are documented only in prose Mostly compatible
E5 String methods on the identity enums (today Caller prints kind:2,source:4) No
E6 Doc pass: per-sentinel comments (with HTTP status for authn), doc links, named callback parameters, Claim.Bool result names No
E7 Move the Cognito verifier into authn/cognito (discretionary) Yes

The record also lists what was considered and not recommended, with reasons. That includes keeping the Handler error return, the explicit iamproof error adapter, the shared edge.Option type and the current config styles. It also notes what is already conformant.

Validation

  • Every claim was checked against the source code, go doc -all output and the accepted decision records. E1 reopens part of decision 0011; the record says so and asks the owner to confirm.
  • All 34 cited style-guide and Go-doc anchors and all relative links resolve. The record renders correctly, and git diff --check is clean.
  • No Go files changed, so the Go test suite was not rerun.

Limitations

  • The resolution is pending: merging this PR records the proposals, not approval to implement them.
  • Package names in E1 and E7 are suggestions and are listed as open questions.

Record decision 0026, a review of every exported identifier in edge, identity, authn, iamproof and authz against Google's Go style guide and the primary sources it links. It proposes seven separately approvable changes before the first release, lists the alternatives considered and not recommended, and leaves the resolution pending owner review.
@ajbeck
ajbeck added this pull request to stack #7 September 27, 2026 13:32
@ajbeck ajbeck changed the title docs: propose exported API changes from Go style review docs: record exported API review and approval of E1-E6 Sep 27, 2026
@ajbeck
ajbeck marked this pull request as ready for review September 27, 2026 15:04
@ajbeck
ajbeck merged commit b940feb into main Sep 27, 2026
8 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