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-26-3f5bf0)](docs/plugins.md)
[![Plugins](https://img.shields.io/badge/plugins-27-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
126 changes: 126 additions & 0 deletions adapter/planetscale.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
package adapter

import (
"cmp"
"context"
"encoding/json"
"fmt"
"time"

"github.com/patch-it-dev/patch-it-plugins/fetch"
"gopkg.in/yaml.v3"
)

const (
// planetscaleRepo is PlanetScale's Terraform provider, which keeps a copy
// of the PlanetScale API spec at planetscaleSpecPath.
planetscaleRepo = "planetscale/terraform-provider-planetscale"
// planetscaleSpecPath is the spec in that repo: a copy of
// https://planetscale.com/docs/openapi.yaml, which has no versions,
// committed when it changes.
planetscaleSpecPath = "schemas/openapi.yaml"
)

// PlanetScale adapts the PlanetScale API spec for the openapi plugin. The
// repo tags no spec releases, so a tag here is the commit that last changed
// the spec, as for Supabase.
//
// The zero value reads GitHub. The fields point it at another server, for
// tests.
type PlanetScale struct {
APIBase string // GitHub's REST API; "" is https://api.github.com
RawBase string // files at a commit; "" is https://raw.githubusercontent.com
}

var _ Adapter = PlanetScale{}

func (PlanetScale) API() string { return "planetscale" }

func (p PlanetScale) api(path string) string {
return cmp.Or(p.APIBase, "https://api.github.com") + "/repos/" + planetscaleRepo + path
}

// LatestTag is the SHA of the newest commit that changed the spec.
func (p PlanetScale) LatestTag(ctx context.Context) (string, error) {
body, err := fetch.Get(ctx, p.api("/commits?path="+planetscaleSpecPath+"&per_page=1"), githubHeaders())
if err != nil {
return "", fmt.Errorf("looking up planetscale'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 planetscale spec")
}
return commits[0].SHA, nil
}

// Fetch downloads the spec at commit sha and converts it from YAML to JSON,
// which is what diff.Parse reads (as for Algolia).
//
// Version is the commit's date (YYYY-MM-DD): the API has no version of its
// own (`info.version` is a fixed "v1", checked 2026-11-19), so the date the
// spec changed is the closest thing to "the API version the change arrived
// in".
//
// A file that isn't a spec is an error, not an empty API: diffed against the
// last one, it would read as every operation removed. The commits that
// changed the file include one that deleted it (f33a0c3b35, 2025-12-04;
// it came back the same day), where the raw URL answers 404: fetch.Get's
// error. A file served 200 that has no paths (emptied, or a stub page like
// "404: Not Found", which YAML reads as a one-key mapping) is refused here.
func (p PlanetScale) Fetch(ctx context.Context, sha string) (Spec, error) {
meta, err := fetch.Get(ctx, p.api("/commits/"+sha), githubHeaders())
if err != nil {
return Spec{}, fmt.Errorf("looking up planetscale 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 := cmp.Or(p.RawBase, "https://raw.githubusercontent.com") + "/" + planetscaleRepo + "/" + commit.SHA + "/" + planetscaleSpecPath
body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth
if err != nil {
return Spec{}, fmt.Errorf("fetching planetscale spec %s: %w", sha, err)
}
var doc map[string]any
if err := yaml.Unmarshal(body, &doc); err != nil {
return Spec{}, fmt.Errorf("parsing planetscale spec %s as yaml: %w", sha, err)
}
if paths, _ := doc["paths"].(map[string]any); len(paths) == 0 {
return Spec{}, fmt.Errorf("planetscale spec %s has no paths: not a spec", sha)
}
content, err := json.Marshal(doc)
if err != nil {
return Spec{}, fmt.Errorf("converting planetscale spec %s to json: %w", sha, err)
}
// The server is "https://api.planetscale.com/v1" and the paths leave out
// /v1 (all 32 versions, 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.
if content, err = ServerBasePath(content); err != nil {
return Spec{}, fmt.Errorf("planetscale 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 (PlanetScale) SourcePointer(content []byte) func(string) string { return BasePathPointer(content) }

var _ Reshaper = PlanetScale{}
93 changes: 93 additions & 0 deletions adapter/planetscale_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
package adapter

import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
)

const planetscaleSHA = "fc13e09d0c18b893aabd3e02d175d13957bba677"

// fakePlanetScaleGitHub serves the commits list, one commit by any prefix of
// planetscaleSHA, and the spec at planetscaleSHA (404 when spec is "").
func fakePlanetScaleGitHub(t *testing.T, commitsJSON, spec string) PlanetScale {
t.Helper()
const repo = "/api/repos/planetscale/terraform-provider-planetscale"
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch p := r.URL.Path; {
case p == repo+"/commits" && r.URL.Query().Get("path") == "schemas/openapi.yaml":
w.Write([]byte(commitsJSON))
case strings.HasPrefix(p, repo+"/commits/") && strings.HasPrefix(planetscaleSHA, strings.TrimPrefix(p, repo+"/commits/")):
w.Write([]byte(`{"sha":"` + planetscaleSHA + `","commit":{"committer":{"date":"2026-11-09T09:16:32Z"}}}`))
case p == "/raw/planetscale/terraform-provider-planetscale/"+planetscaleSHA+"/schemas/openapi.yaml" && spec != "":
w.Write([]byte(spec))
default:
http.Error(w, "404: Not Found", http.StatusNotFound)
}
}))
t.Cleanup(srv.Close)
return PlanetScale{APIBase: srv.URL + "/api", RawBase: srv.URL + "/raw"}
}

func TestPlanetScaleLatestTagIsTheNewestSpecCommit(t *testing.T) {
p := fakePlanetScaleGitHub(t, `[{"sha":"`+planetscaleSHA+`"},{"sha":"older"}]`, "")
tag, err := p.LatestTag(context.Background())
if err != nil || tag != planetscaleSHA {
t.Errorf("got %q, %v; want %s", tag, err, planetscaleSHA)
}
p = fakePlanetScaleGitHub(t, `[]`, "")
if _, err := p.LatestTag(context.Background()); err == nil {
t.Error("no commit: want an error")
}
}

// The version is the commit's date, since the API has none (info.version is
// a fixed v1); the source is pinned to the full SHA even when a short one is
// asked for; the YAML becomes JSON with its values unchanged.
func TestPlanetScaleFetchPinsTheFullSHAAndDatesByCommit(t *testing.T) {
const spec = "openapi: 3.0.1\ninfo:\n version: v1\npaths:\n /organizations:\n get:\n description: |-\n Deprecated. Use x instead.\n responses:\n \"200\":\n description: OK\n"
p := fakePlanetScaleGitHub(t, "", spec)
got, err := p.Fetch(context.Background(), "fc13e09d")
if err != nil {
t.Fatal(err)
}
if want := p.RawBase + "/planetscale/terraform-provider-planetscale/" + planetscaleSHA + "/schemas/openapi.yaml"; got.Version != "2026-11-09" || got.SourceURL != want {
t.Errorf("got version %q, url %s", got.Version, got.SourceURL)
}
var doc struct {
Paths map[string]map[string]struct {
Description string `json:"description"`
} `json:"paths"`
}
if err := json.Unmarshal(got.Content, &doc); err != nil || doc.Paths["/organizations"]["get"].Description != "Deprecated. Use x instead." {
t.Errorf("content %s (%v)", got.Content, err)
}
}

// A file that isn't a spec fails the fetch: diffed, it would read as every
// operation removed. The commit that deleted the file (f33a0c3b35) answers
// 404; a stub served 200 has no paths.
func TestPlanetScaleFetchRefusesWhatIsntASpec(t *testing.T) {
for name, body := range map[string]string{
"deleted (404)": "",
"404 stub": "404: Not Found",
"no paths": "openapi: 3.0.1\ninfo:\n version: v1\n",
"empty paths": "openapi: 3.0.1\npaths: {}\n",
"not yaml": "openapi: [3.0.1\n",
"a yaml scalar": "Not Found",
"html error": "<html><body>Not Found</body></html>",
"paths a string": "openapi: 3.0.1\npaths: none\n",
} {
p := fakePlanetScaleGitHub(t, "", body)
if _, err := p.Fetch(context.Background(), planetscaleSHA); err == nil {
t.Errorf("%s: want an error", name)
}
}
p := fakePlanetScaleGitHub(t, "", "openapi: 3.0.1\npaths:\n /x:\n get: {}\n")
if _, err := p.Fetch(context.Background(), "0000000"); err == nil {
t.Error("unknown commit: want an error")
}
}
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": 26,
"count": 27,
"plugins": [
{
"id": "algolia-ingestion",
Expand Down Expand Up @@ -173,6 +173,16 @@
"status": "live",
"provider_page": "providers/openai-models.md"
},
{
"id": "planetscale",
"provider": "PlanetScale",
"layer": "api",
"watches": "API operations deprecated, and deprecated operations removed, between commits of the spec, said in the operation's description",
"format": "openapi",
"source_url": "https://github.com/planetscale/terraform-provider-planetscale",
"status": "live",
"provider_page": "providers/planetscale.md"
},
{
"id": "posthog",
"provider": "PostHog",
Expand Down
1 change: 1 addition & 0 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe
| [`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 |
| [`planetscale`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/planetscale.md) | PlanetScale | API | API operations deprecated, and deprecated operations removed, between commits of the spec, said in the operation's description | `openapi` | [planetscale/terraform-provider-planetscale](https://github.com/planetscale/terraform-provider-planetscale) (`schemas/openapi.yaml`) | 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
12 changes: 8 additions & 4 deletions plugins/openapi/openapi.go
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
// Package openapi is the source plugin for an API that publishes an OpenAPI
// spec per release (Stripe, Datadog, GitLab, GitHub, Vercel, Supabase,
// Algolia, Elasticsearch, Sentry, Neon): fetch the newest spec, diff it
// against the last one seen, normalize the changes into events, and attach
// migration hints from the API's changelog when it has one. It can also replay
// two given releases.
// Algolia, Elasticsearch, Sentry, Neon, Convex, PlanetScale): fetch the newest
// spec, diff it against the last one seen, normalize the changes into events,
// and attach migration hints from the API's changelog when it has one. It can
// also replay two given releases.
package openapi

import (
Expand Down Expand Up @@ -55,6 +55,10 @@ func init() {
// 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})
// No Hints: PlanetScale's changelog is product news, not keyed by
// operation. Operation deprecations only, said in the description: see
// planetscale.go.
plugin.Register(Plugin{Adapter: adapter.PlanetScale{}, Diff: planetscaleDiff, Keep: planetscaleKeep})
}

// requestSide keeps the changes to what callers send. GitLab's response
Expand Down
49 changes: 49 additions & 0 deletions plugins/openapi/planetscale.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
package openapi

import (
"regexp"

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

// planetscaleDiff is how the PlanetScale API spec says what it says:
//
// - Deprecations are only in the description's first words, "Deprecated.
// Use GET /organizations/:organization/databases/:database/branches/:branch/change-requests
// instead.": the spec has never set the `deprecated` flag (none in any
// of the 32 versions of schemas/openapi.yaml in
// planetscale/terraform-provider-planetscale, 2025-11-11 to 2026-11-09,
// nor in the live https://planetscale.com/docs/openapi.yaml on
// 2026-11-19). If it ever does, the operation is quoted whole, so the
// words come with it.
// - Path parameters get renamed, and that isn't a change for callers.
var planetscaleDiff = diff.Options{PathTemplates: true, QuoteDeprecatedOperation: true, DeprecatedDescription: planetscaleDeprecatedDescription}

// planetscaleDeprecatedWords is the way every deprecation in the history is
// written: the description starts "Deprecated." (the others start with what
// the operation does, or with an empty line, then "### Authorization"). Only
// at the start,
// so not a description that mentions deprecation further on; and with the
// period or a colon, so not "Deprecated, storage shrinking is part of
// storage autoscaling.", which the spec writes on properties.
var planetscaleDeprecatedWords = regexp.MustCompile(`(?i)^\s*deprecated[.:]`)

func planetscaleDeprecatedDescription(description string) bool {
return planetscaleDeprecatedWords.MatchString(description)
}

// planetscaleKeep keeps operation deprecations, and removals of operations
// the old spec had marked deprecated. Over the 31 consecutive pairs of the
// spec's history that's 5 events, all on 2026-11-09 (fc13e09d): GET and
// DELETE .../bouncers/{bouncer}/resizes, GET .../neki-changes, GET and
// DELETE .../neki-changes/{id}. Everything else is dropped:
//
// - 41 operations left the spec, none deprecated first. 6 of them, on
// 2026-10-03, were the read-only replica operations renamed to
// dedicated read replicas, and planetscale/planetscale-go still sends
// the old paths ("the deprecated read-only-replicas path", main on
// 2026-11-19): left the spec isn't stopped working.
// - Property changes and new operations, as for vercel: 226 type changes
// on 2025-12-06 alone, when the spec switched whole numbers to
// `integer`.
var planetscaleKeep = deprecationsOnly(planetscaleDiff)
Loading
Loading