diff --git a/README.md b/README.md index b25e164..5a1a8e7 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ [![Go Reference](https://pkg.go.dev/badge/github.com/patch-it-dev/patch-it-plugins.svg)](https://pkg.go.dev/github.com/patch-it-dev/patch-it-plugins) [![Go version](https://img.shields.io/github/go-mod/go-version/patch-it-dev/patch-it-plugins)](go.mod) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-3f5bf0)](LICENSE) -[![Plugins](https://img.shields.io/badge/plugins-25-3f5bf0)](docs/plugins.md) +[![Plugins](https://img.shields.io/badge/plugins-26-3f5bf0)](docs/plugins.md) [![Docs](https://img.shields.io/badge/docs-docs.patch--it.dev-3f5bf0)](https://docs.patch-it.dev) [![Discussions](https://img.shields.io/github/discussions/patch-it-dev/patch-it-plugins)](https://github.com/patch-it-dev/patch-it-plugins/discussions) diff --git a/adapter/convex.go b/adapter/convex.go new file mode 100644 index 0000000..31cc11c --- /dev/null +++ b/adapter/convex.go @@ -0,0 +1,110 @@ +package adapter + +import ( + "context" + "encoding/json" + "fmt" + "time" + + "github.com/patch-it-dev/patch-it-plugins/fetch" +) + +// Variables, not constants, only so tests can point them at a local server. +var ( + // convexCommitsURL lists the commits that changed the Deployment API + // spec in get-convex/convex-backend, newest first; with per_page=1, the + // newest. + convexCommitsURL = "https://api.github.com/repos/get-convex/convex-backend/commits?path=npm-packages/@convex-dev/platform/deployment-openapi.json&per_page=1" + // convexCommitURL is one commit, for its date. + convexCommitURL = "https://api.github.com/repos/get-convex/convex-backend/commits/%s" + // convexSpecURLTemplate is the Deployment API spec at one commit: 68 + // commits from 2025-08-19 to 2026-11-16 (checked 2026-11-19), and a + // commit never changes. + convexSpecURLTemplate = "https://raw.githubusercontent.com/get-convex/convex-backend/%s/npm-packages/@convex-dev/platform/deployment-openapi.json" +) + +// Convex adapts the Convex Deployment API spec (`{deployment-url}/api/v1`) +// in get-convex/convex-backend for the openapi plugin. A tag here is the +// commit that last changed the spec, as for Supabase. +// +// The repo does tag releases, `precompiled-YYYY-MM-DD-` (1,213 of +// them), but they are daily builds of the self-hosted backend, not releases +// of the API: several a day, ordered only by commit date, the spec unchanged +// in most. The spec at a tag is the spec at the last commit before it that +// changed the file, so reading those commits sees every state a tag would, +// with one GitHub call for the newest instead of paging through the tags. +type Convex struct{} + +var _ Adapter = Convex{} + +func (Convex) API() string { return "convex" } + +// LatestTag is the SHA of the newest commit that changed the spec. +func (Convex) LatestTag(ctx context.Context) (string, error) { + body, err := fetch.Get(ctx, convexCommitsURL, githubHeaders()) + if err != nil { + return "", fmt.Errorf("looking up convex's latest spec commit: %w", err) + } + var commits []struct { + SHA string `json:"sha"` + } + if err := json.Unmarshal(body, &commits); err != nil { + return "", fmt.Errorf("parsing github commits response: %w", err) + } + if len(commits) == 0 || commits[0].SHA == "" { + return "", fmt.Errorf("github lists no commit that changed the convex spec") + } + return commits[0].SHA, nil +} + +// Fetch downloads the spec at commit sha. +// +// Version is the commit's committer date (YYYY-MM-DD, UTC): the Deployment +// API has no version of its own (`/api/v1`, info.version a fixed "1.0.0" in +// every commit, checked 2026-11-19), so the date the spec changed is the +// closest thing to "the API version the change arrived in". +func (Convex) Fetch(ctx context.Context, sha string) (Spec, error) { + meta, err := fetch.Get(ctx, fmt.Sprintf(convexCommitURL, sha), githubHeaders()) + if err != nil { + return Spec{}, fmt.Errorf("looking up convex spec commit %s: %w", sha, err) + } + var commit struct { + SHA string `json:"sha"` + Commit struct { + Committer struct { + Date time.Time `json:"date"` + } `json:"committer"` + } `json:"commit"` + } + if err := json.Unmarshal(meta, &commit); err != nil { + return Spec{}, fmt.Errorf("parsing github commit %s: %w", sha, err) + } + if commit.SHA == "" || commit.Commit.Committer.Date.IsZero() { + return Spec{}, fmt.Errorf("github commit %s has no sha or date", sha) + } + // Pin to the full SHA even when given a short one: the citation must + // name exactly one document. + url := fmt.Sprintf(convexSpecURLTemplate, commit.SHA) + body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth + if err != nil { + return Spec{}, fmt.Errorf("fetching convex spec %s: %w", sha, err) + } + if !json.Valid(body) { + return Spec{}, fmt.Errorf("convex spec %s is not valid json", sha) + } + // The server is "{deployment-url}/api/v1" and the paths leave out /api/v1 + // (all 68 commits, checked 2026-11-19). Moved into the paths, an + // operation is named by the path a caller sends, and a spec that ever + // moved it (as Sentry's did) can't read as every deprecated operation + // removed. + content, err := ServerBasePath(body) + if err != nil { + return Spec{}, fmt.Errorf("convex spec %s: %w", sha, err) + } + return Spec{Content: content, Version: commit.Commit.Committer.Date.UTC().Format("2006-01-02"), SourceURL: url}, nil +} + +// SourcePointer: see BasePathPointer. +func (Convex) SourcePointer(content []byte) func(string) string { return BasePathPointer(content) } + +var _ Reshaper = Convex{} diff --git a/adapter/convex_test.go b/adapter/convex_test.go new file mode 100644 index 0000000..0316b4d --- /dev/null +++ b/adapter/convex_test.go @@ -0,0 +1,118 @@ +package adapter + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" +) + +// fakeConvexGitHub serves the commits list, one commit, and specs by path. +func fakeConvexGitHub(t *testing.T, commitsJSON string, commits, specs map[string]string) *httptest.Server { + t.Helper() + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch { + case r.URL.Path == "/commits": + w.Write([]byte(commitsJSON)) + case strings.HasPrefix(r.URL.Path, "/commits/"): + body, ok := commits[strings.TrimPrefix(r.URL.Path, "/commits/")] + if !ok { + http.Error(w, `{"message":"No commit found"}`, http.StatusUnprocessableEntity) + return + } + w.Write([]byte(body)) + default: + body, ok := specs[r.URL.Path] + if !ok { + http.NotFound(w, r) + return + } + w.Write([]byte(body)) + } + })) + t.Cleanup(srv.Close) + oldList, oldOne, oldSpec := convexCommitsURL, convexCommitURL, convexSpecURLTemplate + convexCommitsURL = srv.URL + "/commits" + convexCommitURL = srv.URL + "/commits/%s" + convexSpecURLTemplate = srv.URL + "/%s/spec.json" + t.Cleanup(func() { convexCommitsURL, convexCommitURL, convexSpecURLTemplate = oldList, oldOne, oldSpec }) + return srv +} + +const convexSHA = "5e5159cbea5188e9da5400febda1b031a233eea0" + +func TestConvexLatestTagIsTheNewestSpecCommit(t *testing.T) { + fakeConvexGitHub(t, `[{"sha":"`+convexSHA+`"},{"sha":"older"}]`, nil, nil) + tag, err := Convex{}.LatestTag(context.Background()) + if err != nil || tag != convexSHA { + t.Errorf("got %q, %v; want %s", tag, err, convexSHA) + } +} + +func TestConvexLatestTagRejectsNoCommit(t *testing.T) { + fakeConvexGitHub(t, `[]`, nil, nil) + if _, err := (Convex{}).LatestTag(context.Background()); err == nil { + t.Error("no commit: want an error") + } +} + +// The version is the commit's committer date, in UTC, since the Deployment +// API has none (its info.version is a fixed 1.0.0); the source is pinned to +// the full SHA even when a short one is asked for, and a spec whose server +// has no path is passed through byte for byte. +func TestConvexFetchPinsTheFullSHAAndDatesByCommit(t *testing.T) { + const body = `{"openapi":"3.1.0","info":{"version":"1.0.0"},"paths":{}}` + srv := fakeConvexGitHub(t, "", map[string]string{ + "5e5159cbea": `{"sha":"` + convexSHA + `","commit":{"committer":{"date":"2026-11-05T19:36:44-08:00"}}}`, + }, map[string]string{"/" + convexSHA + "/spec.json": body}) + spec, err := Convex{}.Fetch(context.Background(), "5e5159cbea") + if err != nil { + t.Fatal(err) + } + if spec.Version != "2026-11-06" || spec.SourceURL != srv.URL+"/"+convexSHA+"/spec.json" || string(spec.Content) != body { + t.Errorf("got version %q, url %s, content %s", spec.Version, spec.SourceURL, spec.Content) + } +} + +// Convex's server is "{deployment-url}/api/v1": Fetch moves /api/v1 into the +// paths, so an operation is named by the path a caller sends, and +// SourcePointer points back into the path as published. +func TestConvexFetchMovesTheServerPathIntoThePaths(t *testing.T) { + const body = `{"openapi":"3.1.0","servers":[{"url":"{deployment-url}/api/v1"}],"paths":{"/list_log_streams":{"get":{}}}}` + fakeConvexGitHub(t, "", map[string]string{ + "5e5159cbea": `{"sha":"` + convexSHA + `","commit":{"committer":{"date":"2026-11-05T19:36:44Z"}}}`, + }, map[string]string{"/" + convexSHA + "/spec.json": body}) + spec, err := Convex{}.Fetch(context.Background(), "5e5159cbea") + if err != nil { + t.Fatal(err) + } + var doc struct { + Paths map[string]any `json:"paths"` + } + if err := json.Unmarshal(spec.Content, &doc); err != nil { + t.Fatal(err) + } + if _, ok := doc.Paths["/api/v1/list_log_streams"]; !ok || len(doc.Paths) != 1 { + t.Errorf("paths %v, want only /api/v1/list_log_streams", doc.Paths) + } + if got := (Convex{}).SourcePointer(spec.Content)("/paths/~1api~1v1~1list_log_streams/get"); got != "/paths/~1list_log_streams/get" { + t.Errorf("SourcePointer = %s, want /paths/~1list_log_streams/get", got) + } +} + +func TestConvexFetchFailures(t *testing.T) { + commit := `{"sha":"` + convexSHA + `","commit":{"committer":{"date":"2026-11-05T19:36:44Z"}}}` + for name, c := range map[string]struct{ commits, specs map[string]string }{ + "unknown commit": {nil, nil}, + "commit without date": {map[string]string{"x": `{"sha":"` + convexSHA + `"}`}, nil}, + "spec missing": {map[string]string{"x": commit}, nil}, + "invalid json": {map[string]string{"x": commit}, map[string]string{"/" + convexSHA + "/spec.json": ""}}, + } { + fakeConvexGitHub(t, "", c.commits, c.specs) + if _, err := (Convex{}).Fetch(context.Background(), "x"); err == nil { + t.Errorf("%s: want an error", name) + } + } +} diff --git a/adapter/sentry.go b/adapter/sentry.go index 7b66eba..1c4c97f 100644 --- a/adapter/sentry.go +++ b/adapter/sentry.go @@ -251,12 +251,18 @@ func ServerBasePath(body []byte) ([]byte, error) { } // serverPath is the path of a server URL ("/api/0" for -// "https://{region}.sentry.io/api/0"), without a trailing slash; "" for -// none. Read by hand: url.Parse refuses the {region} variable in the host. +// "https://{region}.sentry.io/api/0", "/api/v1" for Convex's +// "{deployment-url}/api/v1", whose whole origin is a variable), without a +// trailing slash; "" for none. Read by hand: url.Parse refuses a variable in +// the host. func serverPath(u string) string { _, rest, ok := strings.Cut(u, "://") if !ok { - return "" + if !strings.HasPrefix(u, "{") || !strings.Contains(u, "}") { + return "" + } + _, rest, _ = strings.Cut(u, "}") + return strings.TrimRight(rest, "/") } i := strings.Index(rest, "/") if i < 0 { diff --git a/adapter/sentry_test.go b/adapter/sentry_test.go index 81f29cb..acb179f 100644 --- a/adapter/sentry_test.go +++ b/adapter/sentry_test.go @@ -170,8 +170,13 @@ func TestSentryBasePathRefusesWhatItCantMove(t *testing.T) { } } +// A server whose whole origin is a variable (Convex's "{deployment-url}/api/v1") +// still has a path to move. func TestServerPath(t *testing.T) { for in, want := range map[string]string{ + "{deployment-url}/api/v1": "/api/v1", + "{deployment-url}/api/v1/": "/api/v1", + "{deployment-url}": "", "https://{region}.sentry.io/api/0": "/api/0", "https://{region}.sentry.io/api/0/": "/api/0", "https://{region}.sentry.io": "", diff --git a/docs/plugins.json b/docs/plugins.json index 86b7ea8..2095189 100644 --- a/docs/plugins.json +++ b/docs/plugins.json @@ -1,7 +1,7 @@ { "_comment": "Generated from the plugin registry and docs/plugins.md by `make plugins-json` (go run ./cmd/list-plugins). Don't edit by hand.", "$schema": "./plugins.schema.json", - "count": 25, + "count": 26, "plugins": [ { "id": "algolia-ingestion", @@ -63,6 +63,16 @@ "status": "live", "provider_page": "providers/cloudflare.md" }, + { + "id": "convex", + "provider": "Convex", + "layer": "api", + "watches": "Deployment API operations deprecated, and deprecated operations removed, between commits of the spec", + "format": "openapi", + "source_url": "https://github.com/get-convex/convex-backend", + "status": "live", + "provider_page": "providers/convex.md" + }, { "id": "datadog", "provider": "Datadog", diff --git a/docs/plugins.md b/docs/plugins.md index be79095..ec35d49 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -21,6 +21,7 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe | [`elasticsearch`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/elasticsearch.md) | Elastic | API | Elasticsearch REST API operations deprecated, and deprecated operations removed, between released minor versions of the spec | `openapi` | [elastic/elasticsearch-specification](https://github.com/elastic/elasticsearch-specification) (`output/openapi/elasticsearch-openapi.json`) | live | | [`sentry`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/sentry.md) | Sentry | API | REST API operations deprecated between releases of the spec, most of them in the operation's description | `openapi` | [getsentry/sentry releases](https://github.com/getsentry/sentry/releases) (`openapi-derefed.json` on each `api@` release) | live | | [`neon`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/neon.md) | Neon | API | Neon API operations deprecated, and deprecated operations removed, between commits of the spec | `openapi` | [neondatabase/neon-pkgs](https://github.com/neondatabase/neon-pkgs) (`packages/sdk/spec/neon-openapi.json`) | live | +| [`convex`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/convex.md) | Convex | API | Deployment API operations deprecated, and deprecated operations removed, between commits of the spec | `openapi` | [get-convex/convex-backend](https://github.com/get-convex/convex-backend) (`npm-packages/@convex-dev/platform/deployment-openapi.json`) | live | | [`mongodb-atlas`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/mongodb-atlas.md) | MongoDB | API | Atlas Administration API versions deprecated and removed at their sunset date, per endpoint, from MongoDB's own API changelog | `apichangelog` | [mongodb/openapi `changelog/changelog.json`](https://github.com/mongodb/openapi/blob/main/changelog/changelog.json) | live | | [`openai-models`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/openai-models.md) | OpenAI | AI models | Model deprecations and shutdown dates (Chat Completions and Responses text models) | `retirements` | [OpenAI deprecations](https://developers.openai.com/api/docs/deprecations) | live | | [`anthropic-models`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/anthropic-models.md) | Anthropic | AI models | Model deprecations and retirement dates (Messages API models) | `retirements` | [Anthropic model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations) | live | diff --git a/plugins/openapi/convex.go b/plugins/openapi/convex.go new file mode 100644 index 0000000..e57101e --- /dev/null +++ b/plugins/openapi/convex.go @@ -0,0 +1,29 @@ +package openapi + +import "github.com/patch-it-dev/patch-it-plugins/diff" + +// convexDiff is how the Convex Deployment API spec says what it says: +// +// - Deprecations use the `deprecated` flag, and the description says what +// to use instead ("Deprecated: use `GET /integrations` instead."), so the +// event quotes the whole operation, not the bare `true`. Convex's docs +// build drops flagged operations, "since they stay served only for +// existing callers" (npm-packages/docs/scripts/prepare-openapi-specs.js). +// - PathTemplates, as for every spec here: a renamed path parameter isn't a +// change for callers. None has been renamed in this spec yet. +var convexDiff = diff.Options{PathTemplates: true, QuoteDeprecatedOperation: true} + +// convexKeep keeps operation deprecations, and removals of operations the old +// spec had marked deprecated. In the spec's history (68 commits, 2025-08-19 +// to 2026-11-16) that's 6 events, all on 2026-11-05: the six log stream +// operations, deprecated for the /integrations ones added on 2026-10-30. +// No operation has left the spec. Everything else is dropped: +// +// - Request and response property changes: 18 property removals, 16 type +// changes, 10 schema removals and 3 properties no longer required over +// the history, most of them in the +// data sync, usage-limit and S3 export APIs. On 2026-07-14 the optional +// `name` left the usage-limit request and response, while the server +// didn't refuse a request that still sent it: see the drop test. +// - New operations: nobody has to fix code for a new endpoint. +var convexKeep = deprecationsOnly(convexDiff) diff --git a/plugins/openapi/convex_test.go b/plugins/openapi/convex_test.go new file mode 100644 index 0000000..4d81e48 --- /dev/null +++ b/plugins/openapi/convex_test.go @@ -0,0 +1,164 @@ +package openapi + +import ( + "context" + "fmt" + "os" + "strings" + "testing" + + "github.com/patch-it-dev/patch-it-plugins/adapter" + "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/kit/kittest" +) + +// convexCommits are the spec commits saved under testdata/ (trimmed to the +// operations involved, values unchanged; checked 2026-11-19): short SHA -> +// full SHA and committer date. +var convexCommits = map[string][2]string{ + "f35879bb": {"f35879bb396491942bf8ecbc8ef5e4280499f89f", "2026-10-30"}, + "5e5159cb": {"5e5159cbea5188e9da5400febda1b031a233eea0", "2026-11-05"}, + "3f6edf7a": {"3f6edf7ab8f3f98e027f317633246a19348eabcc", "2026-07-14"}, + "3ead9091": {"3ead909103b7f5897f529c031e80991ad174b07e", "2026-07-14"}, +} + +// fakeConvexAdapter serves the saved copies, cited by the real URL each was +// copied from, as adapter.Convex.Fetch cites it. +type fakeConvexAdapter struct{ latest string } + +func (fakeConvexAdapter) API() string { return "convex" } + +func (f fakeConvexAdapter) LatestTag(context.Context) (string, error) { return f.latest, nil } + +func (fakeConvexAdapter) Fetch(_ context.Context, tag string) (adapter.Spec, error) { + c, ok := convexCommits[tag] + if !ok { + return adapter.Spec{}, fmt.Errorf("no saved copy for %s", tag) + } + body, err := os.ReadFile(convexFile(tag)) + if err != nil { + return adapter.Spec{}, err + } + // As adapter.Convex.Fetch does: /api/v1 moved from the server URL into + // the paths. + content, err := adapter.ServerBasePath(body) + if err != nil { + return adapter.Spec{}, err + } + return adapter.Spec{Content: content, Version: c[1], SourceURL: convexURL(tag)}, nil +} + +func (fakeConvexAdapter) SourcePointer(content []byte) func(string) string { + return adapter.BasePathPointer(content) +} + +func convexFile(tag string) string { return "testdata/convex-" + tag + ".json" } + +func convexURL(tag string) string { + return "https://raw.githubusercontent.com/get-convex/convex-backend/" + convexCommits[tag][0] + "/npm-packages/@convex-dev/platform/deployment-openapi.json" +} + +// convexPlugin is the plugin exactly as registered, over the saved copies. +func convexPlugin(latest string) Plugin { + return Plugin{Adapter: fakeConvexAdapter{latest: latest}, Diff: convexDiff, Keep: convexKeep} +} + +// convexReplacements are the six log stream operations Convex deprecated on +// 2026-11-05, and the /integrations operation each description names +// instead (added 2026-10-30). The commit that deprecated them says "The +// routes still work, so existing callers and older dashboards keep working." +var convexReplacements = map[string]string{ + "GET /api/v1/list_log_streams": "`GET /integrations`", + "GET /api/v1/get_log_stream/{id}": "`GET /integrations/{id}`", + "POST /api/v1/create_log_stream": "`POST /integrations`", + "POST /api/v1/update_log_stream/{id}": "`PATCH /integrations/{id}`", + "POST /api/v1/delete_log_stream/{id}": "`DELETE /integrations/{id}`", + "POST /api/v1/rotate_webhook_secret/{id}": "`POST /integrations/{id}/rotate_webhook_secret`", +} + +// The golden test: the only deprecations in the Deployment API spec's +// history, replayed from the commit before (f35879bb) to the one that made +// them (5e5159cb). Each is a deprecation, not breaking, cites 5e5159cb, and +// quotes the whole operation, so the flag and the replacement are in the +// excerpt. +func TestConvexGolden(t *testing.T) { + ctx := context.Background() + s := openStore(t) + if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, convexPlugin(""), "f35879bb", "5e5159cb"); err != nil || rejected { + t.Fatalf("replay: rejected=%v err=%v", rejected, err) + } + events := kittest.Stored(t, s) + if len(events) != len(convexReplacements) { + for _, e := range events { + t.Logf("got: %s", e.Description) + } + t.Fatalf("stored %d events, want %d", len(events), len(convexReplacements)) + } + for _, e := range events { + instead, ok := convexReplacements[e.Subject.Operation] + if !ok { + t.Errorf("unexpected event %s", e.Subject.Operation) + continue + } + if e.ChangeType != event.ChangeTypeDeprecation || e.Breaking || e.Version != "2026-11-05" { + t.Errorf("%s: %s breaking=%v version %s, want a 2026-11-05 deprecation", e.Subject.Operation, e.ChangeType, e.Breaking, e.Version) + } + if e.SourceURL != convexURL("5e5159cb") { + t.Errorf("%s: source_url %s", e.Subject.Operation, e.SourceURL) + } + if node := jsonNode(t, convexFile("5e5159cb"), e.SourcePointer); node != e.SourceExcerpt && !truncated(e.SourceExcerpt, node) { + t.Errorf("%s: excerpt doesn't match 5e5159cb#%s", e.Subject.Operation, e.SourcePointer) + } + if !strings.Contains(e.SourceExcerpt, `"deprecated":true`) || !strings.Contains(e.SourceExcerpt, "Deprecated: use "+instead+" instead.") { + t.Errorf("%s: excerpt lacks the flag or %s: %.300s", e.Subject.Operation, instead, e.SourceExcerpt) + } + } + kittest.Golden(t, "testdata/golden/convex.json", events) + + // As a daily ingest, the same six events. + s = openStore(t) + env := vercelEnv(s) + for _, tag := range []string{"f35879bb", "5e5159cb"} { + if rejected, err := kittest.Run(ctx, env, s, convexPlugin(tag)); err != nil || rejected { + t.Fatalf("run %s: rejected=%v err=%v", tag, rejected, err) + } + } + if got := kittest.Stored(t, s); len(got) != len(convexReplacements) { + t.Errorf("ingest stored %d events, want %d", len(got), len(convexReplacements)) + } +} + +// The pinned drop test. On 2026-07-14 (3ead9091, "Remove name from usage +// limits") the optional, nullable `name` left the usage-limit request and +// response, unmarked. Convex's commit says it "was never editable in the UI +// (always `None` on create, only echoed back)", and the request type at that +// commit doesn't deny unknown fields, so a caller still sending it isn't +// rejected. No event. +func TestConvexDropsPropertyChangesThatWerentDeprecations(t *testing.T) { + ctx := context.Background() + s := openStore(t) + if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, convexPlugin(""), "3f6edf7a", "3ead9091"); err != nil || rejected { + t.Fatalf("replay: rejected=%v err=%v", rejected, err) + } + if events := kittest.Stored(t, s); len(events) != 0 { + t.Fatalf("stored %d events, want none", len(events)) + } + // Without the filter the same pair reports two breaking removals of + // `name`, one per schema, and nothing else. + s = openStore(t) + p := convexPlugin("") + p.Keep = nil + if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "3f6edf7a", "3ead9091"); err != nil { + t.Fatal(err) + } + unfiltered := kittest.Stored(t, s) + var removed int + for _, e := range unfiltered { + if e.Breaking && strings.HasPrefix(e.Description, "Property name removed from schema UsageLimitConfig") { + removed++ + } + } + if removed != 2 || len(unfiltered) != 2 { + t.Errorf("unfiltered: %d events, %d of them `name` removals; want 2 and 2", len(unfiltered), removed) + } +} diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index 33f7c43..9275ee8 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -52,6 +52,9 @@ func init() { // No Hints: Neon's changelog is a weekly digest, not keyed by operation. // Only operation deprecations and removals: see neon.go. plugin.Register(Plugin{Adapter: adapter.Neon{}, Diff: neonDiff, Keep: neonKeep}) + // No Hints: Convex has no API changelog; its news feed is product news. + // Only operation deprecations and removals: see convex.go. + plugin.Register(Plugin{Adapter: adapter.Convex{}, Diff: convexDiff, Keep: convexKeep}) } // requestSide keeps the changes to what callers send. GitLab's response diff --git a/plugins/openapi/registered_test.go b/plugins/openapi/registered_test.go index 45afa1b..b5ba566 100644 --- a/plugins/openapi/registered_test.go +++ b/plugins/openapi/registered_test.go @@ -8,7 +8,7 @@ import ( ) func TestRegistersItself(t *testing.T) { - for _, a := range []adapter.Adapter{adapter.Stripe{}, adapter.Datadog{}, adapter.GitLab{}, adapter.GitHub{}, adapter.Vercel{}, adapter.Supabase{}, adapter.Algolia{Spec: "search"}, adapter.Algolia{Spec: "ingestion"}, adapter.Algolia{Spec: "recommend"}, adapter.Elasticsearch{}, adapter.Sentry{}, adapter.Neon{}} { + for _, a := range []adapter.Adapter{adapter.Stripe{}, adapter.Datadog{}, adapter.GitLab{}, adapter.GitHub{}, adapter.Vercel{}, adapter.Supabase{}, adapter.Algolia{Spec: "search"}, adapter.Algolia{Spec: "ingestion"}, adapter.Algolia{Spec: "recommend"}, adapter.Elasticsearch{}, adapter.Sentry{}, adapter.Neon{}, adapter.Convex{}} { kittest.Registered(t, Plugin{Adapter: a}) } } diff --git a/plugins/openapi/testdata/README.md b/plugins/openapi/testdata/README.md index 71383af..42bd5d8 100644 --- a/plugins/openapi/testdata/README.md +++ b/plugins/openapi/testdata/README.md @@ -31,6 +31,8 @@ Each pair is a real breaking change between two releases of a provider's own spe | `neon-5c57d009.json`, `neon-93b93dc9.json` | https://raw.githubusercontent.com/neondatabase/neon-pkgs/5c57d0095a9a4594a3c8b09d499b132902e7c42e/packages/sdk/spec/neon-openapi.json (and `93b93dc9e4d1b4ab48dac6c8ccba76b35541b476`) | 2026-11-19 | Excerpt for testing; © Neon. neondatabase/neon-pkgs is Apache-2.0, but the spec's own `info.license` says "Proprietary" | "Deprecated: to test a branch's already-saved configuration, use `sendNeonAuthEmailProviderTest`" (`POST /projects/{project_id}/branches/{branch_id}/auth/send_test_email`, new in `93b93dc9`) | | `neon-4c6b3be4.json`, `neon-4497de89.json` | https://raw.githubusercontent.com/neondatabase/neon-pkgs/4c6b3be46b1b333e7f910db51218ad144de27179/packages/sdk/spec/neon-openapi.json (and `4497de89a5e84b38956fde686d271f99317b8fdb`) | 2026-11-19 | Excerpt for testing; © Neon. neondatabase/neon-pkgs is Apache-2.0, but the spec's own `info.license` says "Proprietary" | `"/projects/{project_id}/branches/{branch_id}/recover": {` (in `4c6b3be4`, gone in `4497de89` without being deprecated): the drop test | | `neon-api-client-2.7.2.yaml`, `neon-api-client-2.7.3.yaml` | `public-v2-for-users.gen.yaml` in https://registry.npmjs.org/@neondatabase/api-client/-/api-client-2.7.2.tgz (and `api-client-2.7.3.tgz`) | 2026-11-19 | Excerpt for testing; © Neon. The package is MIT, but the spec's own `info.license` says "Proprietary" | "**Deprecated.** Use `GET /consumption_history/projects` (`getConsumptionHistoryPerProject`)" (`GET /consumption_history/account`, in 2.7.2, gone in 2.7.3) | +| `convex-f35879bb.json`, `convex-5e5159cb.json` | https://raw.githubusercontent.com/get-convex/convex-backend/f35879bb396491942bf8ecbc8ef5e4280499f89f/npm-packages/@convex-dev/platform/deployment-openapi.json (and `5e5159cbea5188e9da5400febda1b031a233eea0`) | 2026-11-19 | FSL-1.1-Apache-2.0 (get-convex/convex-backend `LICENSE.md`; the spec's own `info.license` is `LicenseRef-FSL-1.1-Apache-2.0`): excerpt for testing, © Convex, Inc.; maintainers, please confirm | "Deprecated: use `GET /integrations` instead." (`GET /list_log_streams`, and five more log stream operations, new in `5e5159cb`) | +| `convex-3f6edf7a.json`, `convex-3ead9091.json` | https://raw.githubusercontent.com/get-convex/convex-backend/3f6edf7ab8f3f98e027f317633246a19348eabcc/npm-packages/@convex-dev/platform/deployment-openapi.json (and `3ead909103b7f5897f529c031e80991ad174b07e`) | 2026-11-19 | FSL-1.1-Apache-2.0 (get-convex/convex-backend `LICENSE.md`; the spec's own `info.license` is `LicenseRef-FSL-1.1-Apache-2.0`): excerpt for testing, © Convex, Inc.; maintainers, please confirm | `"name": {` in `UsageLimitConfigRequest` and `UsageLimitConfigResponse` (in `3f6edf7a`, gone in `3ead9091` without being deprecated): the drop test | The Elasticsearch copies keep `openapi`, `info` and the paths involved, every line unchanged; the 9.2 copy's paths are all gone in 9.2, so its `"paths": {}` is the one line that isn't in the original. @@ -41,5 +43,6 @@ The Supabase copies keep each value unchanged but are re-indented: the source is The Sentry copies keep `openapi`, `info`, `servers` and the path items involved, whole, in their original order except that `servers` comes before `paths`, every line copied unchanged (bar the trailing comma after a path item that's now last); `components` and `tags` left out. Each pair gives the same events as the full files, with the filter and with the variants the tests use (flag only, "deprecat" anywhere). The tests serve them as GitHub would, with each commit's date and each tag's release date. The Neon copies are excerpts, not whole files: the spec says its license is "Proprietary" whatever the license of the repo or package that ships it. The JSON copies keep `openapi`, `servers`, `info` (without its `contact`) and the path items involved, whole and in their original order, every line copied unchanged (bar the trailing comma after a member that's now last); `components` left out. The YAML copies keep, by lines, `openapi`, `servers`, `info`'s `title`, `version` and `license`, and the path items involved; they're a different source from the plugin's (the npm package @neondatabase/api-client, succeeded by @neon/sdk and not released since 2.7.3), used only to check that the removal of an operation marked deprecated is kept. +The Convex copies keep `openapi`, `info`, `servers` and the path items involved, whole and in their original order, every line copied unchanged (bar the trailing comma after a path item or schema that's now last); the usage-limit pair also keeps the component schemas those operations reach, the log stream pair none. The source is FSL-1.1-Apache-2.0 (each version becomes Apache-2.0 two years after it's published), which allows copying for a permitted purpose; these are short excerpts kept for testing, but a maintainer should confirm that before release. Each pair gives the same changes as the full files, with and without the filter. The management API spec (`management-openapi.json`, `info.license` `LicenseRef-Convex`, not defined anywhere in the repo) is neither read nor saved. Stripe's spec isn't saved here: its tests use small specs written inline. diff --git a/plugins/openapi/testdata/convex-3ead9091.json b/plugins/openapi/testdata/convex-3ead9091.json new file mode 100644 index 0000000..f0de886 --- /dev/null +++ b/plugins/openapi/testdata/convex-3ead9091.json @@ -0,0 +1,309 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Convex Deployment API", + "description": "Admin API for interacting with deployments.", + "license": { + "name": "LicenseRef-FSL-1.1-Apache-2.0", + "identifier": "LicenseRef-FSL-1.1-Apache-2.0" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "{deployment-url}/api/v1", + "description": "Your Convex deployment", + "variables": { + "deployment-url": { + "default": "https://happy-animal-123.convex.cloud", + "description": "Your deployment URL" + } + } + } + ], + "paths": { + "/list_usage_limits": { + "get": { + "tags": [ + "Usage Limits" + ], + "summary": "List usage limits", + "description": "Get all usage limit configs for a deployment.", + "operationId": "list_usage_limits", + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListUsageLimitsResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/create_usage_limit": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Create usage limit", + "description": "Create a new usage limit config for a deployment.", + "operationId": "create_usage_limit", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitConfigRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/update_usage_limit/{id}": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Update usage limit", + "description": "Replace an existing usage limit config for a deployment.", + "operationId": "update_usage_limit", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the usage limit to update", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitConfigRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/delete_usage_limit/{id}": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Delete usage limit", + "description": "Delete an existing usage limit config for a deployment.", + "operationId": "delete_usage_limit", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the usage limit to delete", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "" + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + } + }, + "components": { + "schemas": { + "ListUsageLimitsResponse": { + "type": "object", + "required": [ + "usageLimits" + ], + "properties": { + "usageLimits": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UsageLimitConfigResponse" + } + } + } + }, + "UsageLimitConfigRequest": { + "type": "object", + "required": [ + "metric", + "window", + "limitType", + "limit", + "enabled" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "limit": { + "type": "integer", + "format": "int64", + "minimum": 1 + }, + "limitType": { + "type": "string" + }, + "metric": { + "$ref": "#/components/schemas/UsageLimitMetric" + }, + "window": { + "type": "string" + } + } + }, + "UsageLimitConfigResponse": { + "type": "object", + "required": [ + "id", + "metric", + "window", + "limitType", + "limit", + "enabled" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "id": { + "type": "string" + }, + "limit": { + "type": "integer", + "format": "int64", + "minimum": 1 + }, + "limitType": { + "type": "string" + }, + "metric": { + "$ref": "#/components/schemas/UsageLimitMetric" + }, + "window": { + "type": "string" + } + } + }, + "UsageLimitMetric": { + "type": "string", + "enum": [ + "functionCalls", + "databaseIoGb", + "dataEgressGb", + "searchQueryGb", + "queryMutationComputeGbHours", + "actionComputeConvexGbHours", + "actionComputeNodeJsGbHours", + "actionComputeCpuGbHours" + ] + }, + "UsageLimitResponse": { + "type": "object", + "required": [ + "usageLimit" + ], + "properties": { + "usageLimit": { + "$ref": "#/components/schemas/UsageLimitConfigResponse" + } + } + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/convex-3f6edf7a.json b/plugins/openapi/testdata/convex-3f6edf7a.json new file mode 100644 index 0000000..929c4a2 --- /dev/null +++ b/plugins/openapi/testdata/convex-3f6edf7a.json @@ -0,0 +1,321 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Convex Deployment API", + "description": "Admin API for interacting with deployments.", + "license": { + "name": "LicenseRef-FSL-1.1-Apache-2.0", + "identifier": "LicenseRef-FSL-1.1-Apache-2.0" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "{deployment-url}/api/v1", + "description": "Your Convex deployment", + "variables": { + "deployment-url": { + "default": "https://happy-animal-123.convex.cloud", + "description": "Your deployment URL" + } + } + } + ], + "paths": { + "/list_usage_limits": { + "get": { + "tags": [ + "Usage Limits" + ], + "summary": "List usage limits", + "description": "Get all usage limit configs for a deployment.", + "operationId": "list_usage_limits", + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListUsageLimitsResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/create_usage_limit": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Create usage limit", + "description": "Create a new usage limit config for a deployment.", + "operationId": "create_usage_limit", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitConfigRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/update_usage_limit/{id}": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Update usage limit", + "description": "Replace an existing usage limit config for a deployment.", + "operationId": "update_usage_limit", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the usage limit to update", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitConfigRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/delete_usage_limit/{id}": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Delete usage limit", + "description": "Delete an existing usage limit config for a deployment.", + "operationId": "delete_usage_limit", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the usage limit to delete", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "" + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + } + }, + "components": { + "schemas": { + "ListUsageLimitsResponse": { + "type": "object", + "required": [ + "usageLimits" + ], + "properties": { + "usageLimits": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UsageLimitConfigResponse" + } + } + } + }, + "UsageLimitConfigRequest": { + "type": "object", + "required": [ + "metric", + "window", + "limitType", + "limit", + "enabled" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "limit": { + "type": "integer", + "format": "int64", + "minimum": 1 + }, + "limitType": { + "type": "string" + }, + "metric": { + "$ref": "#/components/schemas/UsageLimitMetric" + }, + "name": { + "type": [ + "string", + "null" + ] + }, + "window": { + "type": "string" + } + } + }, + "UsageLimitConfigResponse": { + "type": "object", + "required": [ + "id", + "metric", + "window", + "limitType", + "limit", + "enabled" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "id": { + "type": "string" + }, + "limit": { + "type": "integer", + "format": "int64", + "minimum": 1 + }, + "limitType": { + "type": "string" + }, + "metric": { + "$ref": "#/components/schemas/UsageLimitMetric" + }, + "name": { + "type": [ + "string", + "null" + ] + }, + "window": { + "type": "string" + } + } + }, + "UsageLimitMetric": { + "type": "string", + "enum": [ + "functionCalls", + "databaseIoGb", + "dataEgressGb", + "searchQueryGb", + "queryMutationComputeGbHours", + "actionComputeConvexGbHours", + "actionComputeNodeJsGbHours", + "actionComputeCpuGbHours" + ] + }, + "UsageLimitResponse": { + "type": "object", + "required": [ + "usageLimit" + ], + "properties": { + "usageLimit": { + "$ref": "#/components/schemas/UsageLimitConfigResponse" + } + } + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/convex-5e5159cb.json b/plugins/openapi/testdata/convex-5e5159cb.json new file mode 100644 index 0000000..13f1d8c --- /dev/null +++ b/plugins/openapi/testdata/convex-5e5159cb.json @@ -0,0 +1,301 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Convex Deployment API", + "description": "Admin API for interacting with deployments.", + "license": { + "name": "LicenseRef-FSL-1.1-Apache-2.0", + "identifier": "LicenseRef-FSL-1.1-Apache-2.0" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "{deployment-url}/api/v1", + "description": "Your Convex deployment", + "variables": { + "deployment-url": { + "default": "https://happy-animal-123.convex.cloud", + "description": "Your deployment URL" + } + } + } + ], + "paths": { + "/list_log_streams": { + "get": { + "tags": [ + "Log Streams" + ], + "summary": "List log streams", + "description": "List configs for all existing log streams in a deployment.\n\nDeprecated: use `GET /integrations` instead.", + "operationId": "list_log_streams", + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LogStreamConfig" + } + } + } + } + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/get_log_stream/{id}": { + "get": { + "tags": [ + "Log Streams" + ], + "summary": "Get log stream", + "description": "Get the config for a specific log stream by id.\n\nDeprecated: use `GET /integrations/{id}` instead.", + "operationId": "get_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to retrieve", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LogStreamConfig" + } + } + } + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/delete_log_stream/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Delete log stream", + "description": "Delete the deployment's log stream with the given id.\n\nDeprecated: use `DELETE /integrations/{id}` instead.", + "operationId": "delete_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to delete", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "" + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/create_log_stream": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Create log stream", + "description": "Create a new log stream for the deployment. Errors if a log stream of the\ngiven type already exists.\n\nDeprecated: use `POST /integrations` instead.", + "operationId": "create_log_stream", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateLogStreamArgs" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateLogStreamResponse" + } + } + } + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/update_log_stream/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Update log stream", + "description": "Update an existing log stream for the deployment. Omit a field to keep the\nexisting value, and use `null` to unset a field.\n\nDeprecated: use `PATCH /integrations/{id}` instead.", + "operationId": "update_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to update", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateLogStreamArgs" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "" + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/rotate_webhook_secret/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Rotate webhook log stream secret", + "description": "Rotate the secret for the webhook log stream.\n\nDeprecated: use `POST /integrations/{id}/rotate_webhook_secret` instead.", + "operationId": "rotate_webhook_secret", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the webhook log stream for which to rotate the secret", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RotateLogStreamSecretResponse" + } + } + } + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/convex-f35879bb.json b/plugins/openapi/testdata/convex-f35879bb.json new file mode 100644 index 0000000..79a4fa2 --- /dev/null +++ b/plugins/openapi/testdata/convex-f35879bb.json @@ -0,0 +1,295 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Convex Deployment API", + "description": "Admin API for interacting with deployments.", + "license": { + "name": "LicenseRef-FSL-1.1-Apache-2.0", + "identifier": "LicenseRef-FSL-1.1-Apache-2.0" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "{deployment-url}/api/v1", + "description": "Your Convex deployment", + "variables": { + "deployment-url": { + "default": "https://happy-animal-123.convex.cloud", + "description": "Your deployment URL" + } + } + } + ], + "paths": { + "/list_log_streams": { + "get": { + "tags": [ + "Log Streams" + ], + "summary": "List log streams", + "description": "List configs for all existing log streams in a deployment.", + "operationId": "list_log_streams", + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LogStreamConfig" + } + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/get_log_stream/{id}": { + "get": { + "tags": [ + "Log Streams" + ], + "summary": "Get log stream", + "description": "Get the config for a specific log stream by id.", + "operationId": "get_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to retrieve", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LogStreamConfig" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/delete_log_stream/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Delete log stream", + "description": "Delete the deployment's log stream with the given id.", + "operationId": "delete_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to delete", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "" + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/create_log_stream": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Create log stream", + "description": "Create a new log stream for the deployment. Errors if a log stream of the\ngiven type already exists.", + "operationId": "create_log_stream", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateLogStreamArgs" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateLogStreamResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/update_log_stream/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Update log stream", + "description": "Update an existing log stream for the deployment. Omit a field to keep the\nexisting value, and use `null` to unset a field.", + "operationId": "update_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to update", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateLogStreamArgs" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "" + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/rotate_webhook_secret/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Rotate webhook log stream secret", + "description": "Rotate the secret for the webhook log stream.", + "operationId": "rotate_webhook_secret", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the webhook log stream for which to rotate the secret", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RotateLogStreamSecretResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/golden/convex.json b/plugins/openapi/testdata/golden/convex.json new file mode 100644 index 0000000..e5aa4d8 --- /dev/null +++ b/plugins/openapi/testdata/golden/convex.json @@ -0,0 +1,128 @@ +[ + { + "id": 1, + "fingerprint": "sha256:3009cdf0f6116b14f13ec28bd6eca6aa3be6eabe66d34fb5db7454881671f770", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /api/v1/create_log_stream" + }, + "description": "Operation POST /api/v1/create_log_stream marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1create_log_stream/post", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Create a new log stream for the deployment. Errors if a log stream of the\\ngiven type already exists.\\n\\nDeprecated: use `POST /integrations` instead.\",\"operationId\":\"create_log_stream\",\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/CreateLogStreamArgs\"}}},\"required\":true},\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/CreateLogStreamResponse\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Create log stream\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 2, + "fingerprint": "sha256:a42a45fdc091e8fe2b4e151c38e131c3195f846cd26148ddc5db8d9d02b6cbac", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /api/v1/delete_log_stream/{id}" + }, + "description": "Operation POST /api/v1/delete_log_stream/{id} marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1delete_log_stream~1{id}/post", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Delete the deployment's log stream with the given id.\\n\\nDeprecated: use `DELETE /integrations/{id}` instead.\",\"operationId\":\"delete_log_stream\",\"parameters\":[{\"description\":\"id of the log stream to delete\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Delete log stream\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 3, + "fingerprint": "sha256:930075f543a07bd23b16f582788fd8b8c079dc4bc2d3d6cd43c2acd583a995da", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "GET /api/v1/get_log_stream/{id}" + }, + "description": "Operation GET /api/v1/get_log_stream/{id} marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1get_log_stream~1{id}/get", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Get the config for a specific log stream by id.\\n\\nDeprecated: use `GET /integrations/{id}` instead.\",\"operationId\":\"get_log_stream\",\"parameters\":[{\"description\":\"id of the log stream to retrieve\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/LogStreamConfig\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Get log stream\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 4, + "fingerprint": "sha256:f5a5c1ee8bb1ce5a406d952df079517005f92e83a2c09729e782ebf7e892af71", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "GET /api/v1/list_log_streams" + }, + "description": "Operation GET /api/v1/list_log_streams marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1list_log_streams/get", + "source_excerpt": "{\"deprecated\":true,\"description\":\"List configs for all existing log streams in a deployment.\\n\\nDeprecated: use `GET /integrations` instead.\",\"operationId\":\"list_log_streams\",\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"items\":{\"$ref\":\"#/components/schemas/LogStreamConfig\"},\"type\":\"array\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"List log streams\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 5, + "fingerprint": "sha256:be79bb14968226260e9856e3ec45a8e3ad5795f6ee67be1a380e59f1acc8ab92", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /api/v1/rotate_webhook_secret/{id}" + }, + "description": "Operation POST /api/v1/rotate_webhook_secret/{id} marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1rotate_webhook_secret~1{id}/post", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Rotate the secret for the webhook log stream.\\n\\nDeprecated: use `POST /integrations/{id}/rotate_webhook_secret` instead.\",\"operationId\":\"rotate_webhook_secret\",\"parameters\":[{\"description\":\"id of the webhook log stream for which to rotate the secret\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/RotateLogStreamSecretResponse\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Rotate webhook log stream secret\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 6, + "fingerprint": "sha256:942f605d4201eddbb6b6b98d66dd306b6154248fca40225b5586aba1da633610", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /api/v1/update_log_stream/{id}" + }, + "description": "Operation POST /api/v1/update_log_stream/{id} marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1update_log_stream~1{id}/post", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Update an existing log stream for the deployment. Omit a field to keep the\\nexisting value, and use `null` to unset a field.\\n\\nDeprecated: use `PATCH /integrations/{id}` instead.\",\"operationId\":\"update_log_stream\",\"parameters\":[{\"description\":\"id of the log stream to update\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/UpdateLogStreamArgs\"}}},\"required\":true},\"responses\":{\"200\":{\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Update log stream\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + } +] diff --git a/providers/README.md b/providers/README.md index c1b723c..810da16 100644 --- a/providers/README.md +++ b/providers/README.md @@ -20,6 +20,7 @@ One page per plugin id: `providers/.md`. Start from [`_template.md`](_templ | [elasticsearch.md](elasticsearch.md) | `elasticsearch` | `openapi` | | [sentry.md](sentry.md) | `sentry` | `openapi` | | [neon.md](neon.md) | `neon` | `openapi` | +| [convex.md](convex.md) | `convex` | `openapi` | | [openai-models.md](openai-models.md) | `openai-models` | `retirements` | | [anthropic-models.md](anthropic-models.md) | `anthropic-models` | `retirements` | | [anthropic.md](anthropic.md) | `anthropic` | `migrationguide` | diff --git a/providers/convex.md b/providers/convex.md new file mode 100644 index 0000000..c848d5c --- /dev/null +++ b/providers/convex.md @@ -0,0 +1,48 @@ +# Convex (`convex`) + +## What it watches + +The Convex Deployment API (`{deployment-url}/api/v1`, the platform API for managing one deployment: environment variables, log streams and integrations, usage limits, data sync): operations Convex marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. + +Format plugin: `openapi` (`plugins/openapi`), with `adapter.Convex`. + +## Why this source + +- **Source:** `npm-packages/@convex-dev/platform/deployment-openapi.json` in [get-convex/convex-backend](https://github.com/get-convex/convex-backend), pinned to the commit that last changed it (`https://raw.githubusercontent.com/get-convex/convex-backend//npm-packages/@convex-dev/platform/deployment-openapi.json`). The newest such commit comes from the GitHub commits API. Checked on 2026-11-19. +- **Why a commit, not a release tag:** the repo tags `precompiled-YYYY-MM-DD-` builds (1,213 of them), but those are daily builds of the self-hosted backend, not releases of the API. There are several on some days, ordered only by commit date, and the spec is the same in most of them. The spec at a tag is the spec at the last commit before it that changed the file, so the commits see every version a tag would, and finding the newest takes one call instead of paging through the tags. A commit never changes, so it can be cited and replayed. +- **Why this one:** + - It's Convex's own description of the API: its docs build renders the API reference from it. + - It marks deprecations with the `deprecated` flag and says what to use instead ("Deprecated: use `GET /integrations` instead."). Convex's docs build drops flagged operations, "since they stay served only for existing callers" (`npm-packages/docs/scripts/prepare-openapi-specs.js`). + - There are 68 versions from 2025-08-19, when the spec was added, to 2026-11-16. +- **Alternatives considered:** + - **The Management API spec** (`management-openapi.json`, next to it: teams, projects, deployments). Its `info.license` is `LicenseRef-Convex`, which nothing in the repo defines, so the plugin neither reads nor saves it. + - **The SDK changelogs** (`convex` on npm, `get-convex/convex-js` `CHANGELOG.md`; `convex-py`). One flat list of bullets per version (95 versions in `convex-js`), with no removed or deprecated sections for the `changelog` plugin to read. + - **[Convex News](https://news.convex.dev/)** (RSS at `https://news.convex.dev/rss/`). Product news and announcements, newest post 2026-09-21; it doesn't name API operations. + - **The `@convex-dev/platform` npm package** (0.1.11). Its tarball has only `package.json` and the generated client, not the specs. +- **Quote:** "Deprecated: use `GET /integrations` instead." (`GET /api/v1/list_log_streams`, deprecated in the spec on 2026-11-05) + +## How the provider announces changes + +- **No API version beyond `/api/v1`.** `info.version` is `1.0.0` in every commit, so the event's `version` is the spec commit's committer date (UTC), the closest thing to the API version a change arrived in. The patch-it client keeps a date-versioned API's events only if it's in its list of date-versioned APIs, so `convex` needs to be in it. +- **The spec changes a few times a month,** mostly with new operations and properties as Convex builds out the platform API. +- **Deprecations are rare:** one so far. On 2026-10-30 (`f35879bb`, "Rename log_streaming to integrations") Convex added six `/integrations` operations; on 2026-11-05 (`5e5159cb`) it marked the six log stream operations deprecated, each naming its replacement. The commit says "The routes still work, so existing callers and older dashboards keep working." + +## What the plugin reads and ignores + +- **Reads:** the spec at the newest commit, diffed against the last one. Two events come out of it: + - **Deprecations:** an operation that gains the `deprecated` flag. The event quotes the whole operation, so the replacement Convex names is in the excerpt. + - **Removals (breaking):** an operation that leaves the spec after the previous spec had marked it deprecated. None yet. +- **Operations are named by the path a caller sends,** `GET /api/v1/list_log_streams`: the server URL is `{deployment-url}/api/v1` (since the first commit) and the spec's paths leave out `/api/v1`, so the adapter moves it into the paths (as Sentry's does with `/api/0`). Quotes cite the spec as published. If Convex ever moves `/api/v1` between the server and the paths, the operations stay the same, rather than every deprecated one reading as removed. +- **Matches operations by path template,** as for every spec here. No path parameter has been renamed in this spec yet. +- **Ignores everything else:** + - **Request and response property changes,** and new operations. Over the history the differ finds 18 property removals, 16 type changes, 10 schema removals and 3 properties no longer required, most of them in the data sync, usage-limit and S3 export APIs. The drop test is one of them: on 2026-07-14 (`3ead9091`, "Remove name from usage limits") the optional `name` left the usage-limit request and response; the commit says it "was never editable in the UI (always `None` on create, only echoed back)", and the request type at that commit doesn't reject unknown fields, so a caller still sending it isn't refused. + - **Removals of operations that were never deprecated.** None in the history: no operation has left the spec. +- Over the 68 commits this keeps 6 events, all deprecations on 2026-11-05: `GET /api/v1/list_log_streams`, `GET /api/v1/get_log_stream/{id}`, `POST /api/v1/create_log_stream`, `POST /api/v1/update_log_stream/{id}`, `POST /api/v1/delete_log_stream/{id}`, `POST /api/v1/rotate_webhook_secret/{id}`. +- **Replays** a historical pair (`Replay`, from `f35879bb` to `5e5159cb`) and recreates those six; the golden test also runs them as a daily ingest. The drop test replays `3f6edf7a` to `3ead9091`. + +## Known gaps + +- **Only the Deployment API is covered.** Not the Management API (see above), the client SDKs (`convex` on npm, `convex-py`), or the functions runtime. SDK removals are written as plain bullets in their changelogs, so nothing reads them yet. +- **Removals Convex doesn't mark first aren't events,** even if the endpoint really went away. None has happened yet. +- **Two spec commits on one day share a `version`.** It happened on 13 days in the history. The events stay distinct, because the operation is part of the fingerprint, but the second run's `previous_version` equals its `version`. +- **The patch-it client can't place these events until `convex` is in its list of date-versioned APIs.**