Skip to content

add the neon plugin - #132

Merged
brandonphelps1212 merged 2 commits into
mainfrom
neon-plugin
Nov 20, 2026
Merged

brandonphelps1212 merged 2 commits into
mainfrom
neon-plugin

Conversation

@brandonphelps1212

Copy link
Copy Markdown
Contributor

What this changes

Adds neon, an openapi plugin for Neon's management API. Part of #74 (I11.6 · Watch Neon), under #14.

  • Source: packages/sdk/spec/neon-openapi.json in neondatabase/neon-pkgs, read at the newest commit that changed it. A daily drift check against the live spec (https://neon.com/api_spec/release/v2.json) keeps it current.
  • version is the commit date (YYYY-MM-DD). The API has no version of its own: info.version is v2 in all 23 commits.
  • Rule: Vercel's deprecationsOnly. Deprecations come from the deprecated flag, with the operation quoted (QuoteDeprecatedOperation), so the "use X instead" and "Removal scheduled" text is cited. A removal is kept only if the operation was flagged first.
  • Operation names include /api/v2 (POST /api/v2/projects/…), the path a caller sends. The spec's server is https://console.neon.tech/api/v2. Sentry's helper that moves the server path into the paths is now shared (adapter.ServerBasePath, adapter.BasePathPointer). Sentry's goldens are unchanged.
    • Without it, a spec that ever moved /api/v2 (as Sentry's did in November) would read as all 16 deprecated operations removed: 16 false breaking events.
  • History: over all 23 commits it keeps 1 event: POST /api/v2/projects/{project_id}/branches/{branch_id}/auth/send_test_email, deprecated on 2026-08-23. The 1 unmarked removal (…/recover, which Neon's PR #408 says still routes) is dropped.

For the maintainers: the test data's license

The repo is Apache-2.0, but the spec's own info.license says "Proprietary". So the test data is trimmed excerpts: the operations the tests need, every kept line unchanged, with info.contact left out. The extra removal test uses the same spec from the MIT @neondatabase/api-client npm package. Please confirm that's acceptable.

Needs a client change

neon must be added to the patch-it client's list of date-versioned APIs, like supabase and sentry. Until then the client can't place these events. That's a separate PR in the client repo.

Checklist

  • Added to docs/plugins.md: new row, status live. docs/plugins.json regenerated, README badge 25. I compared the row's words with the plugin.
  • Every commit is signed off (DCO)
  • Golden test: replay 5c57d009 → 93b93dc9, 1 deprecation event.
  • Pinned drop test: 4c6b3be4 → 4497de89, the unmarked removal of …/recover, 0 events. With the filter off it gives exactly that 1 removal, so the test isn't vacuous.
  • Extra test: npm @neondatabase/api-client 2.7.2 → 2.7.3, the removal of GET /api/v2/consumption_history/account. It was flagged deprecated first and is confirmed by Neon's changelog. This is a different source, labelled as such.
  • testdata/README.md rows: URL at the commit, date, license, quote.
  • providers/neon.md from the template, with Why this source and Known gaps:
    • 15 operations are past their "Removal scheduled" dates and still in the spec;
    • the copy lags the live spec by days;
    • the SDKs and changelog have no readable removals.
  • Fetches only through the fetch layer.
  • make check passes.
  • Nothing private.

Notes for the reviewer

An independent review re-derived every number from all 23 commits, the live spec and both npm tarballs.

  • It found no wrong event, and confirmed the trimmed test data gives the same events as the full files.
  • It mutation-tested the keep rule and the quoting.
  • Its findings are fixed in the second commit: the base-path protection, and wording that overstated "nothing says deprecated without the flag" (two operations deprecate a parameter in words).

🤖 Generated with Claude Code

brandonphelps1212 and others added 2 commits November 19, 2026 19:14
Watches the Neon API spec in neondatabase/neon-pkgs (packages/sdk/spec/neon-openapi.json), pinned per commit and versioned by commit date. Keeps operation deprecations and removals of operations marked deprecated first.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: brandonphelps1212 <[email protected]>
Move the server's /api/v2 into the paths with Sentry's helper, now shared
(adapter.ServerBasePath), so a spec that moves it can't read as every
deprecated operation removed; and accurate wording on what says deprecated.

Signed-off-by: brandonphelps1212 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
@claude

claude Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Claude finished @brandonphelps1212's task in 1m 54s —— View job


✅ Ready to merge: the plugin follows every rule, I found no wrong event in what it reads, and build, vet, gofmt, the tests and the leak guard all pass locally. Two things need a maintainer's decision before merging (the test data's license and the client change). Neither is a code problem.

Rules

Rule Status Evidence
Plugin list (Rule 1) ✅ neon is registered in plugins/openapi/openapi.go:57 and has a row in docs/plugins.md between the markers, with absolute links. The id, provider, format (openapi), source and status match the plugin. docs/plugins.json (count 25) and the README badge are regenerated, and go test passes, so the JSON is up to date.
Provider page ✅ providers/neon.md follows the template's sections. Why this source has the link, the check date (2026-11-19), why this source, four alternatives with reasons, and a quote. It is also listed in providers/README.md.
Golden test + quote ✅ TestNeonGolden replays 5c57d009 → 93b93dc9 and gets 1 deprecation. source_url is pinned to the full SHA. The test checks the excerpt against the saved file at source_pointer, and checks that it contains the flag, the "use sendNeonAuthEmailProviderTest" text and x-sunset. testdata/README.md has a row for each file pair (URL, date, license, quote).
Drop test ✅ TestNeonDropsRemovalsThatWerentDeprecated (4c6b3be4 → 4497de89) gives 0 events. With Keep off it gives exactly the one …/recover removal, so the test can actually fail.
Fetch only via env ✅ adapter/neon.go fetches only through fetch.Get. net/http appears only in adapter/neon_test.go (httptest). Tests read files only under testdata/.
Nothing private ✅ I found no credentials, internal hostnames, private links or session links in the code, docs, test data or commit messages. The client change is described as "patch-it's hosted ingestion service", as AGENTS.md asks. The only email is the author's own in the DCO sign-off. leak_guard.py --all is clean.
Commits ✅ Both commits are signed off, the subjects are short and lowercase, and the co-author trailer is kept.

Bugs

None found. What I checked:

  • Keep rule. It reuses Vercel's deprecationsOnly (vercel.go:55). It keeps OperationDeprecated, and it keeps OperationRemoved only when the old operation was flagged. Everything else is dropped, so property changes and new operations can't produce events.
  • Base-path refactor. sentryBasePath → ServerBasePath and Sentry.SourcePointer → BasePathPointer are renames with no change in behaviour. Sentry's tests and goldens pass unchanged. Moving /api/v2 into the paths means a later move of the base path can't produce 16 false removals. The golden's source_pointer (/paths/~1projects~1…/post) points into the spec as published.
  • Version. The version is the commit's UTC date. Fetch resolves short SHAs to the full one before citing, so every citation names exactly one document.

Verified

  • go build ./...: OK
  • go vet ./...: no output
  • gofmt -l .: no output
  • go test -race ./...: every package ok, including adapter and plugins/openapi
  • python3 scripts/leak_guard.py --all: "no banned terms (8 hashed terms checked)"

I did not run make check PATCH_IT=… (the contract check), because this PR doesn't touch contract/fixtures/.

For the maintainers (please decide)

  • Test data license. The spec's info.license says "Proprietary", although both the repo and the npm package are open source (Apache-2.0 and MIT). The PR saves only trimmed excerpts and says so in testdata/README.md. That looks like a reasonable approach to me, but whether it's acceptable is your call, as the PR asks.
  • Client change. Until neon is in the client's list of date-versioned APIs, the client can't place these events (see Known gaps in providers/neon.md). The row says live. That's fine if the client PR lands first or at the same time; if not, you may want to hold the merge until it does.

Non-blocking

  • Optional: if two spec commits ever land on the same UTC day, they get the same version, so version == previous_version. The provider page already lists this as a known gap and it hasn't happened yet. If it does, adding the short SHA to the version (for example 2026-08-23+93b93dc9) would keep versions unique, but that's not needed now.

Thanks for a careful, well-documented PR. Testing with the filter turned off and the separate test of a kept removal are especially useful.

@brandonphelps1212
brandonphelps1212 merged commit 22ac056 into main Nov 20, 2026
5 checks passed
@brandonphelps1212
brandonphelps1212 deleted the neon-plugin branch November 20, 2026 00:30
This was referenced Nov 20, 2026
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