Skip to content

add the convex plugin - #133

Merged
brandonphelps1212 merged 3 commits into
mainfrom
convex-plugin
Nov 20, 2026
Merged

brandonphelps1212 merged 3 commits into
mainfrom
convex-plugin

Conversation

@brandonphelps1212

Copy link
Copy Markdown
Contributor

What this changes

Adds convex, an openapi plugin for Convex's Deployment API. Part of #77 (I11.9 · Watch Convex), under #14.

  • Source: npm-packages/@convex-dev/platform/deployment-openapi.json in get-convex/convex-backend, read at the newest commit that changed it.
    • Convex also tags daily precompiled-* builds (1,213 of them). Those are self-hosted builds, not API releases, and a tag's spec is always the spec at the last commit that changed the file. So commits see every version, and finding the newest takes one call.
  • version is the commit's date (UTC). info.version is 1.0.0 in all 68 commits.
  • Rule: Vercel's deprecationsOnly, with the operation quoted, so "Deprecated: use … instead." is cited.
  • Operation names include /api/v1 (GET /api/v1/list_log_streams), the path a caller sends. It uses the base-path helper shared in add the neon plugin #132. serverPath now also reads a server URL whose whole origin is a variable, like Convex's {deployment-url}/api/v1; Sentry's goldens are unchanged. Without it, a future move of /api/v1 would read as the 6 deprecated operations removed.
  • History: over all 68 commits it keeps 6 events, all deprecations on 2026-11-05: the log-stream routes, each pointing at its /integrations replacement. Convex's commit says "The routes still work". No operation has ever left the spec.
  • Not read: management-openapi.json, whose license (LicenseRef-Convex) is undefined.

For the maintainers: the test data's license

The spec is FSL-1.1-Apache-2.0 (source-available; it becomes Apache-2.0 after two years). The test data is trimmed excerpts, with every kept line unchanged. Please confirm that's acceptable.

Needs a client change

convex must be added to the patch-it client's list of date-versioned APIs, like neon, supabase and sentry. 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 26. I compared the row's words with the plugin.
  • Every commit is signed off (DCO)
  • Golden test: replay f35879bb → 5e5159cb, 6 deprecation events.
  • Pinned drop test: 3f6edf7a → 3ead9091, "Remove name from usage limits", 0 events. With the filter off it gives exactly 2 property removals, so the test isn't vacuous. The server never refused a request still sending name.
  • testdata/README.md rows: URL at the commit, date, license, quote.
  • providers/convex.md from the template, with Why this source and Known gaps: the SDK changelogs have no readable removals; the management API isn't read; only one deprecation so far.
  • Fetches only through the fetch layer.
  • make check passes.
  • Nothing private.

Notes for the reviewer

An independent review replayed all 67 history pairs on the full specs.

  • With the filter, the 6 events are the only output; nothing emitted is wrong.
  • The trimmed and full files give identical events.
  • It mutation-tested the keep rule, the quoting, the committer date and the pinning.

Its suggestions are in the third commit: the base-path protection, and a fuller tally of the property changes.

🤖 Generated with Claude Code

brandonphelps1212 and others added 3 commits November 19, 2026 19:13
Signed-off-by: brandonphelps1212 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
…he path a caller sends

Move the server's /api/v1 into the paths with the shared
adapter.ServerBasePath (now reading a server URL whose origin is a
variable), so a spec that moves it can't read as every deprecated
operation removed. Keep both plugins' rows; badge 26.

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 44s —— View job


✅ Ready to merge: the plugin follows every repo rule, all checks pass locally, and I found no blocking bugs. One date to confirm, and the license question you raised is for a maintainer.

Rules

Rule Status Evidence
Plugin list (Rule 1) ✅ docs/plugins.md has a new convex row between the markers, with absolute links. docs/plugins.json is regenerated (count 26) and the README badge says 26. The row's provider, format, source and "watches" text match adapter.Convex, convexKeep and the registration in plugins/openapi/openapi.go:55.
Provider page ✅ providers/convex.md has every section of _template.md. Why this source gives the link, the date checked (2026-11-19), why this is the best source, four alternatives not used (Management API spec, SDK changelogs, Convex News, the npm package) and a quote. providers/README.md is updated.
Golden test and quote ✅ TestConvexGolden replays f35879bb → 5e5159cb. It stores 6 deprecation events, each with the pinned raw URL and an excerpt that matches the saved file at its source_pointer and contains "deprecated":true and the replacement. The same 6 come out when run as a daily ingest. Each saved file has a row in testdata/README.md with URL, date, license and quote.
Drop test ✅ 3f6edf7a → 3ead9091 stores 0 events. With the filter off it stores exactly 2 name removals, so the test can actually fail.
Fetch only via env ✅ adapter/convex.go fetches only through fetch.Get. net/http appears only in adapter/convex_test.go (httptest).
Nothing private ✅ Only public GitHub URLs. No hostnames, credentials or session links in the code, docs, commits or PR body. Leak guard is clean. Every commit is signed off.

Bugs

None found.

I checked the serverPath change (adapter/sentry.go:258-272) for side effects on the other plugins:

  • A server URL with no :// still returns "" unless it starts with {. So a relative /api/v1 server, or one with no server at all, is still passed through unchanged.
  • Sentry's and Neon's goldens are unchanged and their tests pass.

Precision looks right. deprecationsOnly only keeps:

  • flag deprecations, and
  • removals of operations the old spec had already marked deprecated.

Moving /api/v1 into the paths means a future change to the server URL can't show up as six removals.

Verified

Command Result
go build ./... ok
go vet ./... no output
gofmt -l . no output
go test -race ./... every package ok (plugins/openapi, adapter, internal/pluginlist included)
python3 scripts/leak_guard.py --all "no banned terms (8 hashed terms checked)"

I couldn't run make contract, because it needs a patch-it checkout. I also couldn't look up commit 5e5159cb through the GitHub API, because that call needed approval in this run.

Non-blocking

  • Please confirm the version date. adapter/convex_test.go:203 uses a committer date of 2026-11-05T19:36:44-08:00, which Fetch correctly turns into 2026-11-06 in UTC. But the golden test's fake adapter (plugins/openapi/convex_test.go:400), the golden file and providers/convex.md all say 2026-11-05. If that timestamp is 5e5159cb's real committer date, the live plugin would emit version: "2026-11-06", not what the golden and docs say. If the timestamp is made up, you could switch the test to something like T19:36:44Z so it doesn't look like the real one. If it's real, the convexCommits dates and the "2026-11-05" in the docs should use the UTC date.
  • License, for a maintainer: the test data is trimmed excerpts of an FSL-1.1-Apache-2.0 spec. The PR and testdata/README.md both ask a maintainer to confirm that's acceptable before merge.
  • Client follow-up: convex still has to be added to the patch-it client's list of date-versioned APIs. Until then the client can't place these events (noted under Known gaps).

Thanks for the careful history replay and the non-vacuous drop test, they made this easy to review.

// full SHA and committer date.
var convexCommits = map[string][2]string{
"f35879bb": {"f35879bb396491942bf8ecbc8ef5e4280499f89f", "2026-10-30"},
"5e5159cb": {"5e5159cbea5188e9da5400febda1b031a233eea0", "2026-11-05"},

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking, please confirm: adapter/convex_test.go gives this commit a committer date of 2026-11-05T19:36:44-08:00, and Fetch turns that into 2026-11-06 (UTC). If that timestamp is the real one, the live plugin's version for these six events would be 2026-11-06, not the 2026-11-05 used here, in the golden file and in providers/convex.md.

@brandonphelps1212
brandonphelps1212 merged commit 6709030 into main Nov 20, 2026
7 checks passed
@brandonphelps1212
brandonphelps1212 deleted the convex-plugin branch November 20, 2026 00:34
@brandonphelps1212 brandonphelps1212 mentioned this pull request Nov 20, 2026
15 tasks
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