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-24-3f5bf0)](docs/plugins.md)
[![Plugins](https://img.shields.io/badge/plugins-25-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
106 changes: 106 additions & 0 deletions adapter/neon.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
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 (
// neonCommitsURL lists the commits that changed the Neon API spec in
// neondatabase/neon-pkgs, newest first; with per_page=1, the newest.
neonCommitsURL = "https://api.github.com/repos/neondatabase/neon-pkgs/commits?path=packages/sdk/spec/neon-openapi.json&per_page=1"
// neonCommitURL is one commit, for its date.
neonCommitURL = "https://api.github.com/repos/neondatabase/neon-pkgs/commits/%s"
// neonSpecURLTemplate is the Neon API spec (console.neon.tech/api/v2) at
// one commit. Neon serves it live at
// https://neon.com/api_spec/release/v2.json, which has no versions; the
// copy in neondatabase/neon-pkgs is pulled from there and committed when
// a daily drift check sees it change (23 commits from 2026-06-24 to
// 2026-11-17), and a commit never changes.
neonSpecURLTemplate = "https://raw.githubusercontent.com/neondatabase/neon-pkgs/%s/packages/sdk/spec/neon-openapi.json"
)

// Neon adapts the Neon API spec in neondatabase/neon-pkgs for the openapi
// plugin. The repo tags no spec releases, so a tag here is the commit that
// last changed the spec.
type Neon struct{}

var _ Adapter = Neon{}

func (Neon) API() string { return "neon" }

// LatestTag is the SHA of the newest commit that changed the spec.
func (Neon) LatestTag(ctx context.Context) (string, error) {
body, err := fetch.Get(ctx, neonCommitsURL, githubHeaders())
if err != nil {
return "", fmt.Errorf("looking up neon'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 neon spec")
}
return commits[0].SHA, nil
}

// Fetch downloads the spec at commit sha and moves the server URL's path into
// the paths: see ServerBasePath.
//
// Version is the commit's date (YYYY-MM-DD): the API's only version is the
// `/api/v2` in its URL (info.version a fixed "v2" in all 23 commits, checked
// 2026-11-19), so the date the spec changed is the closest thing to "the API
// version the change arrived in".
func (Neon) Fetch(ctx context.Context, sha string) (Spec, error) {
meta, err := fetch.Get(ctx, fmt.Sprintf(neonCommitURL, sha), githubHeaders())
if err != nil {
return Spec{}, fmt.Errorf("looking up neon 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(neonSpecURLTemplate, commit.SHA)
body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth
if err != nil {
return Spec{}, fmt.Errorf("fetching neon spec %s: %w", sha, err)
}
if !json.Valid(body) {
return Spec{}, fmt.Errorf("neon spec %s is not valid json", sha)
}
// The server is "https://console.neon.tech/api/v2" and the paths don't
// repeat /api/v2 (all 23 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("neon 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 (Neon) SourcePointer(content []byte) func(string) string { return BasePathPointer(content) }

var _ Reshaper = Neon{}
118 changes: 118 additions & 0 deletions adapter/neon_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"
)

// fakeNeonGitHub serves the commits list, one commit, and specs by path.
func fakeNeonGitHub(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 := neonCommitsURL, neonCommitURL, neonSpecURLTemplate
neonCommitsURL = srv.URL + "/commits"
neonCommitURL = srv.URL + "/commits/%s"
neonSpecURLTemplate = srv.URL + "/%s/spec.json"
t.Cleanup(func() { neonCommitsURL, neonCommitURL, neonSpecURLTemplate = oldList, oldOne, oldSpec })
return srv
}

const neonSHA = "93b93dc9e4d1b4ab48dac6c8ccba76b35541b476"

func TestNeonLatestTagIsTheNewestSpecCommit(t *testing.T) {
fakeNeonGitHub(t, `[{"sha":"`+neonSHA+`"},{"sha":"older"}]`, nil, nil)
tag, err := Neon{}.LatestTag(context.Background())
if err != nil || tag != neonSHA {
t.Errorf("got %q, %v; want %s", tag, err, neonSHA)
}
}

func TestNeonLatestTagRejectsNoCommit(t *testing.T) {
fakeNeonGitHub(t, `[]`, nil, nil)
if _, err := (Neon{}).LatestTag(context.Background()); err == nil {
t.Error("no commit: want an error")
}
}

// The version is the commit's date, since the API has none (its
// info.version is a fixed v2); 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 TestNeonFetchPinsTheFullSHAAndDatesByCommit(t *testing.T) {
const body = `{"openapi":"3.0.3","info":{"version":"v2"},"paths":{}}`
srv := fakeNeonGitHub(t, "", map[string]string{
"93b93dc9": `{"sha":"` + neonSHA + `","commit":{"committer":{"date":"2026-08-23T11:50:46Z"}}}`,
}, map[string]string{"/" + neonSHA + "/spec.json": body})
spec, err := Neon{}.Fetch(context.Background(), "93b93dc9")
if err != nil {
t.Fatal(err)
}
if spec.Version != "2026-08-23" || spec.SourceURL != srv.URL+"/"+neonSHA+"/spec.json" || string(spec.Content) != body {
t.Errorf("got version %q, url %s, content %s", spec.Version, spec.SourceURL, spec.Content)
}
}

func TestNeonFetchFailures(t *testing.T) {
commit := `{"sha":"` + neonSHA + `","commit":{"committer":{"date":"2026-08-23T11:50:46Z"}}}`
for name, c := range map[string]struct{ commits, specs map[string]string }{
"unknown commit": {nil, nil},
"commit without date": {map[string]string{"x": `{"sha":"` + neonSHA + `"}`}, nil},
"spec missing": {map[string]string{"x": commit}, nil},
"invalid json": {map[string]string{"x": commit}, map[string]string{"/" + neonSHA + "/spec.json": "<html>"}},
} {
fakeNeonGitHub(t, "", c.commits, c.specs)
if _, err := (Neon{}).Fetch(context.Background(), "x"); err == nil {
t.Errorf("%s: want an error", name)
}
}
}

// Neon's server is "https://console.neon.tech/api/v2": Fetch moves /api/v2
// into the paths, so an operation is named by the path a caller sends, and
// SourcePointer points back into the path as published.
func TestNeonFetchMovesTheServerPathIntoThePaths(t *testing.T) {
const body = `{"openapi":"3.0.3","servers":[{"url":"https://console.neon.tech/api/v2"}],"paths":{"/projects":{"get":{}}}}`
fakeNeonGitHub(t, "", map[string]string{
"93b93dc9": `{"sha":"` + neonSHA + `","commit":{"committer":{"date":"2026-08-23T11:50:46Z"}}}`,
}, map[string]string{"/" + neonSHA + "/spec.json": body})
spec, err := Neon{}.Fetch(context.Background(), "93b93dc9")
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/v2/projects"]; !ok || len(doc.Paths) != 1 {
t.Errorf("paths %v, want only /api/v2/projects", doc.Paths)
}
if got := (Neon{}).SourcePointer(spec.Content)("/paths/~1api~1v2~1projects/get"); got != "/paths/~1projects/get" {
t.Errorf("SourcePointer = %s, want /paths/~1projects/get", got)
}
}
31 changes: 20 additions & 11 deletions adapter/sentry.go
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ func (r sentryReleaseInfo) hasSpec() bool {

// Fetch downloads the spec of an [email protected] release (the release's asset), or
// of a sentry-api-schema tag or commit (the file at it), and moves the
// server URL's path into the paths: see sentryBasePath.
// server URL's path into the paths: see ServerBasePath.
//
// Version is the release's publication date, or a commit's date
// (YYYY-MM-DD): the API has no version of its own (`/api/0`, info.version
Expand Down Expand Up @@ -173,7 +173,7 @@ func (s Sentry) Fetch(ctx context.Context, tag string) (Spec, error) {
if err != nil {
return Spec{}, fmt.Errorf("fetching the sentry %s spec: %w", tag, err)
}
content, err := sentryBasePath(body)
content, err := ServerBasePath(body)
if err != nil {
return Spec{}, fmt.Errorf("sentry %s: %w", tag, err)
}
Expand All @@ -195,13 +195,18 @@ func sentryReleaseMeta(ctx context.Context, url, tag string) (sentryReleaseInfo,
return r, nil
}

// sentryBasePathKey is the root key Fetch records the server path it moved
// basePathKey is the root key ServerBasePath records the server path it moved
// into the paths under. The differ reads only paths and components, so the
// key is never diffed.
const sentryBasePathKey = "x-patch-it-base-path"
const basePathKey = "x-patch-it-base-path"

// sentryBasePath puts the server URL's path back at the front of every path.
// ServerBasePath puts the server URL's path back at the front of every path,
// so an operation is named by the path a caller sends ("GET /api/0/…"), and
// a spec that moves the server's path into its paths (or out of them) reads
// as the same operations, not as every operation removed and added again.
// Used by every adapter whose API has a path in its server URL.
//
// Sentry did move it:
// Until sentry-api-schema 2.0.1 the server was "https://{region}.sentry.io"
// and the paths started "/api/0/"; from 2.1.0 (2026-11-13) the server is
// "https://{region}.sentry.io/api/0" and the paths don't. The URLs a caller
Expand All @@ -213,7 +218,7 @@ const sentryBasePathKey = "x-patch-it-base-path"
// A spec whose server has no path is returned byte for byte. The values are
// otherwise unchanged (numbers kept as written); the path moved is recorded
// for SourcePointer.
func sentryBasePath(body []byte) ([]byte, error) {
func ServerBasePath(body []byte) ([]byte, error) {
dec := json.NewDecoder(bytes.NewReader(body))
dec.UseNumber()
var doc map[string]any
Expand Down Expand Up @@ -241,7 +246,7 @@ func sentryBasePath(body []byte) ([]byte, error) {
moved[base+p] = item
}
doc["paths"] = moved
doc[sentryBasePathKey] = base
doc[basePathKey] = base
return json.Marshal(doc)
}

Expand All @@ -260,10 +265,14 @@ func serverPath(u string) string {
return strings.TrimRight(rest[i:], "/")
}

// SourcePointer turns a pointer into a path Fetch prefixed with the server's
// path back into one into the path as published. Every other pointer, and
// every pointer into a spec Fetch didn't change, is already right.
func (Sentry) SourcePointer(content []byte) func(string) string {
// SourcePointer: see BasePathPointer.
func (Sentry) SourcePointer(content []byte) func(string) string { return BasePathPointer(content) }

// BasePathPointer turns a pointer into a path ServerBasePath prefixed with
// the server's path back into one into the path as published. Every other
// pointer, and every pointer into a spec ServerBasePath didn't change, is
// already right.
func BasePathPointer(content []byte) func(string) string {
var doc struct {
Base string `json:"x-patch-it-base-path"`
}
Expand Down
4 changes: 2 additions & 2 deletions adapter/sentry_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -162,10 +162,10 @@ func TestSentryFetchSchemaTagOrCommit(t *testing.T) {
}

func TestSentryBasePathRefusesWhatItCantMove(t *testing.T) {
if _, err := sentryBasePath([]byte(`{"servers":[{"url":"https://x/api"}],"paths":{"/a":{},"a":{}}}`)); err == nil {
if _, err := ServerBasePath([]byte(`{"servers":[{"url":"https://x/api"}],"paths":{"/a":{},"a":{}}}`)); err == nil {
t.Error("a path without a leading /: want an error")
}
if _, err := sentryBasePath([]byte(`{"servers":[{"url":"https://x/api/0"},{"url":"https://y"}],"paths":{}}`)); err == nil {
if _, err := ServerBasePath([]byte(`{"servers":[{"url":"https://x/api/0"},{"url":"https://y"}],"paths":{}}`)); err == nil {
t.Error("servers with different paths: want an error")
}
}
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": 24,
"count": 25,
"plugins": [
{
"id": "algolia-ingestion",
Expand Down Expand Up @@ -123,6 +123,16 @@
"status": "live",
"provider_page": "providers/mongodb-atlas.md"
},
{
"id": "neon",
"provider": "Neon",
"layer": "api",
"watches": "Neon API operations deprecated, and deprecated operations removed, between commits of the spec",
"format": "openapi",
"source_url": "https://github.com/neondatabase/neon-pkgs",
"status": "live",
"provider_page": "providers/neon.md"
},
{
"id": "newrelic",
"provider": "New Relic",
Expand Down
1 change: 1 addition & 0 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe
| [`algolia-recommend`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/algolia.md) | Algolia | API | Recommend API operations deprecated, and deprecated operations removed, between releases of the spec | `openapi` | [algolia/api-clients-automation](https://github.com/algolia/api-clients-automation) (`specs/bundled/recommend.yml`) | live |
| [`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 |
| [`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
33 changes: 33 additions & 0 deletions plugins/openapi/neon.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
package openapi

import "github.com/patch-it-dev/patch-it-plugins/diff"

// neonDiff is how the Neon API spec says what it says:
//
// - Deprecations use the `deprecated` flag, and only the flag: in the 23
// commits of neondatabase/neon-pkgs's copy (2026-06-24 to 2026-11-17) no
// operation is described as deprecated without it. (Two unflagged
// operations deprecate a parameter in words; those aren't operation
// deprecations.)
// A flagged operation's description says why or when ("Deprecated: to
// test a branch's already-saved configuration, use
// `sendNeonAuthEmailProviderTest`", "Removal scheduled for March 1,
// 2026"), and every one carries an `x-sunset` date, so the event quotes
// the whole operation, not the bare `true`.
// - Path parameters could be renamed without the URL changing; none was in
// this history, but matching by path template costs nothing here and
// keeps a rename from reading as a removal.
var neonDiff = diff.Options{PathTemplates: true, QuoteDeprecatedOperation: true}

// neonKeep keeps operation deprecations, and removals of operations the old
// spec had marked deprecated. In the spec's history that's 1 event: POST
// /projects/{project_id}/branches/{branch_id}/auth/send_test_email,
// deprecated on 2026-08-23. Everything else is dropped:
//
// - One operation left the spec, not deprecated first: POST
// /projects/{project_id}/branches/{branch_id}/recover on 2026-08-09.
// neon-pkgs's own PR for it (#408) says it "was not removed from the API.
// It was removed from the published spec": it still routes.
// - Request and response property changes, new operations: not changes a
// caller has to fix, or not ones the spec's history shows reliably.
var neonKeep = deprecationsOnly(neonDiff)
Loading
Loading