Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
110 changes: 110 additions & 0 deletions adapter/convex.go
Original file line number Diff line number Diff line change
@@ -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-<sha>` (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{}
118 changes: 118 additions & 0 deletions adapter/convex_test.go
Original file line number Diff line number Diff line change
@@ -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": "<html>"}},
} {
fakeConvexGitHub(t, "", c.commits, c.specs)
if _, err := (Convex{}).Fetch(context.Background(), "x"); err == nil {
t.Errorf("%s: want an error", name)
}
}
}
12 changes: 9 additions & 3 deletions adapter/sentry.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
5 changes: 5 additions & 0 deletions adapter/sentry_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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": "",
Expand Down
12 changes: 11 additions & 1 deletion docs/plugins.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down Expand Up @@ -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",
Expand Down
1 change: 1 addition & 0 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
29 changes: 29 additions & 0 deletions plugins/openapi/convex.go
Original file line number Diff line number Diff line change
@@ -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)
Loading
Loading