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

import (
"context"
"encoding/json"
"fmt"
"strings"

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

// Variables, not constants, only so tests can point them at a local server.
var (
flagsmithReleasesURL = "https://api.github.com/repos/Flagsmith/flagsmith/releases/latest"
// flagsmithSpecURLTemplate is the OpenAPI 3.1 description of Flagsmith's
// full REST API (the Admin/Management API and the SDK-facing endpoints
// together), committed at the root of Flagsmith/flagsmith as openapi.yaml
// (checked 2026-11-19). It's generated from the Django backend with
// drf-spectacular (`make generate-full-openapi`) and regenerated on every
// PR that touches api/** by a bot that commits the result back to the PR
// branch (.github/workflows/api-fix-docs-artefacts.yml), so a release tag
// always carries the spec for the code it actually ships. There's also a
// narrower sdk/openapi.yaml, filtered down to the SDK-only endpoints
// (openapi-filter-flagsmith-sdk.yml): this adapter reads the full file so
// Admin/Management API removals aren't missed.
flagsmithSpecURLTemplate = "https://raw.githubusercontent.com/Flagsmith/flagsmith/%s/openapi.yaml"
)

// Flagsmith adapts Flagsmith's own OpenAPI spec for the openapi plugin.
type Flagsmith struct{}

var _ Adapter = Flagsmith{}

func (Flagsmith) API() string { return "flagsmith" }

// LatestTag asks GitHub for Flagsmith's newest release tag, e.g. "v2.293.0".
// Flagsmith tags a release on (almost) every merge to main via release-please,
// so releases/latest is always close to HEAD.
func (Flagsmith) LatestTag(ctx context.Context) (string, error) {
body, err := fetch.Get(ctx, flagsmithReleasesURL, githubHeaders())
if err != nil {
return "", fmt.Errorf("looking up flagsmith's latest release: %w", err)
}
var release struct {
TagName string `json:"tag_name"`
}
if err := json.Unmarshal(body, &release); err != nil {
return "", fmt.Errorf("parsing github release response: %w", err)
}
if release.TagName == "" {
return "", fmt.Errorf("github release response had no tag_name")
}
return release.TagName, nil
}

// Fetch downloads the spec pinned to tag and converts it from YAML to JSON,
// since diff.Parse only reads JSON. This changes no provenance guarantee:
// normalize's excerpt already re-serializes whatever node it quotes rather
// than slicing the original bytes, for every adapter including Stripe's.
//
// Version is the release tag without its "v" ("2.293.0"), not info.version:
// that is a fixed "v1" in every release (checked 2026-11-19), so it can't
// tell two releases apart. The bare version is also what a self-hosted
// instance reports and what a customer tracks as "the Flagsmith version
// we're running".
func (Flagsmith) Fetch(ctx context.Context, tag string) (Spec, error) {
url := fmt.Sprintf(flagsmithSpecURLTemplate, tag)
body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth
if err != nil {
return Spec{}, fmt.Errorf("fetching flagsmith spec %s: %w", tag, err)
}

var doc any
if err := yaml.Unmarshal(body, &doc); err != nil {
return Spec{}, fmt.Errorf("parsing flagsmith spec %s as yaml: %w", tag, err)
}
content, err := json.Marshal(doc)
if err != nil {
return Spec{}, fmt.Errorf("converting flagsmith spec %s to json: %w", tag, err)
}

return Spec{
Content: content,
Version: strings.TrimPrefix(tag, "v"),
SourceURL: url,
}, nil
}
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": 28,
"count": 29,
"plugins": [
{
"id": "algolia-ingestion",
Expand Down Expand Up @@ -103,6 +103,16 @@
"status": "live",
"provider_page": "providers/elasticsearch.md"
},
{
"id": "flagsmith",
"provider": "Flagsmith",
"layer": "api",
"watches": "REST API changes between releases of Flagsmith's own OpenAPI spec (removed endpoints and request parameters)",
"format": "openapi",
"source_url": "https://github.com/Flagsmith/flagsmith/blob/main/openapi.yaml",
"status": "live",
"provider_page": "providers/flagsmith.md"
},
{
"id": "github",
"provider": "GitHub",
Expand Down
1 change: 1 addition & 0 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe
| [`posthog`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/posthog.md) | PostHog | SDK | Members removed in the posthog Python SDK 8.0.0 | `removedmembers` | [posthog-python 7.x to 8.0 migration guide](https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md) | live |
| [`newrelic`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/newrelic.md) | New Relic | SDK | Members removed in the New Relic Python agent 11.0.0 | `removedmembers` | [Python agent 11.0.0 release notes](https://github.com/newrelic/docs-website/blob/f0b4f817bf9a7b76a78e26609369a8a7ce764c8e/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx) | live |
| [`appwrite`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/appwrite.md) | Appwrite | API | REST API operations a server SDK calls that are deprecated between commits of the spec, SDK method renames left out | `openapi` | [appwrite/specs](https://github.com/appwrite/specs) (`specs/<X.Y>.x/open-api3-<X.Y>.x.json`, the newest minor) | live |
| [`flagsmith`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/flagsmith.md) | Flagsmith | API | REST API changes between releases of Flagsmith's own OpenAPI spec (removed endpoints and request parameters) | `openapi` | [github.com/Flagsmith/flagsmith/blob/main/openapi.yaml](https://github.com/Flagsmith/flagsmith/blob/main/openapi.yaml) | live |
<!-- plugins:end -->

## The columns
Expand Down
101 changes: 101 additions & 0 deletions plugins/openapi/flagsmith_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
package openapi

import (
"context"
"encoding/json"
"fmt"
"os"
"strings"
"testing"

"github.com/patch-it-dev/patch-it-plugins/adapter"
"github.com/patch-it-dev/patch-it-plugins/kit/kittest"
"gopkg.in/yaml.v3"
)

// flagsmithTags are the saved copies under testdata/ (checked 2026-11-19):
// tag -> file and the full commit SHA each was copied from.
//
// v2.286.0 / v2.287.0 are release tags: "feat(API): Remove the experimental
// flag update endpoints" (#8736, commit 20cd1c2da) removed three whole
// operations (POST .../delete-segment-override/, .../update-flag-v1/,
// .../update-flag-v2/) between them, each marked "EXPERIMENTAL ENDPOINT -
// Subject to change without notice" in its own description, and listed under
// "Features" in the v2.287.0 release notes.
//
// desc-c3ef832 / desc-f504f16 are two commits, not tags (git log -S on
// openapi.yaml): "feat: rename admin api to management" (#8464, commit
// f504f160d, parent c3ef83244) only reworded two description strings ("the
// Admin API" to "the Management API"); nothing it names changed. The pinned
// drop test.
var flagsmithTags = map[string]string{
"v2.286.0": "testdata/flagsmith-v2.286.0.yaml",
"v2.287.0": "testdata/flagsmith-v2.287.0.yaml",
"c3ef832": "testdata/flagsmith-desc-c3ef832.yaml",
"f504f16": "testdata/flagsmith-desc-f504f16.yaml",
}

func TestFlagsmithRegistersItself(t *testing.T) {
kittest.Registered(t, Plugin{Adapter: adapter.Flagsmith{}})
}

// fakeFlagsmithAdapter serves the saved copies, cited by the real URL each
// was copied from, converted from YAML to JSON and the tag's leading "v"
// trimmed from Version the same way adapter.Flagsmith.Fetch does.
type fakeFlagsmithAdapter struct{}

func (fakeFlagsmithAdapter) API() string { return "flagsmith" }

func (fakeFlagsmithAdapter) LatestTag(context.Context) (string, error) { return "v2.287.0", nil }

func (fakeFlagsmithAdapter) Fetch(_ context.Context, tag string) (adapter.Spec, error) {
file, ok := flagsmithTags[tag]
if !ok {
return adapter.Spec{}, fmt.Errorf("no saved copy for %s", tag)
}
body, err := os.ReadFile(file)
if err != nil {
return adapter.Spec{}, err
}
var doc any
if err := yaml.Unmarshal(body, &doc); err != nil {
return adapter.Spec{}, err
}
content, err := json.Marshal(doc)
if err != nil {
return adapter.Spec{}, err
}
return adapter.Spec{
Content: content,
Version: strings.TrimPrefix(tag, "v"),
SourceURL: "https://raw.githubusercontent.com/Flagsmith/flagsmith/" + tag + "/openapi.yaml",

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Golden doesn't match what production emits. adapter.Flagsmith.Fetch sets Version: strings.TrimPrefix(tag, "v") ("2.287.0"), but this fake sets Version: tag. As a result testdata/golden/flagsmith.json records "version": "v2.287.0" / "previous_version": "v2.286.0", which the real plugin will never produce. Vercel's fake mirrors its adapter on this point. Suggested fix (then regenerate the golden and say so in the PR):

Suggested change
SourceURL: "https://raw.githubusercontent.com/Flagsmith/flagsmith/" + tag + "/openapi.yaml",
Version: strings.TrimPrefix(tag, "v"),

(This needs "strings" in the imports.)

}, nil
}

// The golden test and the replay fixture: the real removal of the three
// experimental flag-update endpoints between v2.286.0 and v2.287.0.
func TestFlagsmithGolden(t *testing.T) {
ctx := context.Background()
env := kittest.Env(t, nil)
sink := env.Baselines.(kittest.Sink)
p := Plugin{Adapter: fakeFlagsmithAdapter{}, Keep: requestSide}
if rejected, err := kittest.Replay(ctx, env, sink, p, "v2.286.0", "v2.287.0"); err != nil || rejected {
t.Fatalf("replay: rejected=%v err=%v", rejected, err)
}
kittest.Golden(t, "testdata/golden/flagsmith.json", kittest.Stored(t, sink))
}

// The pinned drop test: a commit that only reworded two description strings
// ("the Admin API" to "the Management API") must produce no event.
func TestFlagsmithDropsADescriptionOnlyChange(t *testing.T) {
ctx := context.Background()
env := kittest.Env(t, nil)
sink := env.Baselines.(kittest.Sink)
p := Plugin{Adapter: fakeFlagsmithAdapter{}, Keep: requestSide}
if rejected, err := kittest.Replay(ctx, env, sink, p, "c3ef832", "f504f16"); err != nil || rejected {
t.Fatalf("replay: rejected=%v err=%v", rejected, err)
}
if got := kittest.Stored(t, sink); len(got) != 0 {
t.Errorf("%d events from a description-only change, want none", len(got))
}
}
6 changes: 6 additions & 0 deletions plugins/openapi/openapi.go
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,12 @@ func init() {
// Operation deprecations only, SDK method renames left out: see
// appwrite.go.
plugin.Register(Plugin{Adapter: adapter.Appwrite{}, Diff: appwriteDiff, Keep: appwriteKeep})
// No Hints: Flagsmith's release notes are product news, not keyed by
// operation. requestSide, same reason as GitLab's: a named request-body
// schema shared by several operations (FeatureValue, SegmentOverride)
// reads as its own removal, side "response" by the differ's default,
// whether or not any operation that used it is actually gone.
plugin.Register(Plugin{Adapter: adapter.Flagsmith{}, Keep: requestSide})
}

// requestSide keeps the changes to what callers send. GitLab's response
Expand Down
4 changes: 4 additions & 0 deletions plugins/openapi/testdata/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ Each pair is a real breaking change between two releases of a provider's own spe
| `appwrite-1.9.x-8c00ba35-server.json`, `appwrite-1.9.x-7d74bf9f-server.json` | https://raw.githubusercontent.com/appwrite/specs/8c00ba356b01d43fbc6c88c60fb2a4fc99e04b40/specs/1.9.x/open-api3-1.9.x-server.json (and `7d74bf9f3c0c990745e822f5935bcfaca310fd06`) | 2026-11-19 | BSD-3-Clause (appwrite/specs) | `"replaceWith": "tablesDB.createTransaction"` (`x-appwrite.deprecated` of `POST /databases/transactions`, flagged in `7d74bf9f` with 13 more) |
| `appwrite-2.4.x-98cc1a25.json`, `appwrite-2.4.x-06e6fafa.json` | https://raw.githubusercontent.com/appwrite/specs/98cc1a25215d3cead3a64f9bd4574a9c5b1ec87b/specs/2.4.x/open-api3-2.4.x.json (and `06e6fafa4d1ae3c815843ff0b02a56e6e5582756`) | 2026-11-19 | BSD-3-Clause (appwrite/specs) | `"server"` in `x-appwrite.platforms` of `POST /account/recovery/otp` and 12 more operations (in `98cc1a25`, none deprecated; off them in `06e6fafa`, on again in 2.5.x the next day): the drop test |
| `appwrite-1.7.x-ac705cd3-server.json`, `appwrite-1.8.x-ac705cd3-server.json` | https://raw.githubusercontent.com/appwrite/specs/ac705cd3e9d5e3a0693b7e40189eb1e66883e341/specs/1.7.x/open-api3-1.7.x-server.json (and `specs/1.8.x/open-api3-1.8.x-server.json` at the same commit) | 2026-11-19 | BSD-3-Clause (appwrite/specs) | `"replaceWith": "account.createMFAAuthenticator"` on `POST /account/mfa/authenticators/{type}`, whose `x-appwrite.methods` are `createMfaAuthenticator` and `createMFAAuthenticator` (one of 21 SDK method renames flagged in 1.8.x) |
| `flagsmith-v2.286.0.yaml`, `flagsmith-v2.287.0.yaml` | https://raw.githubusercontent.com/Flagsmith/flagsmith/v2.286.0/openapi.yaml (and `v2.287.0`) | 2026-11-19 | BSD-3-Clause (Flagsmith/flagsmith; also the spec's own `info.license`) | "**EXPERIMENTAL ENDPOINT** - Subject to change without notice." (`POST .../delete-segment-override/` and two more, removed in `v2.287.0`) |
| `flagsmith-desc-c3ef832.yaml`, `flagsmith-desc-f504f16.yaml` | https://raw.githubusercontent.com/Flagsmith/flagsmith/c3ef83244bfb4b1d65ab6fc5ff45412659dd61f3/openapi.yaml (and `f504f160dcf40b16baace0506a04dfda8fd6332c`, commits not tags) | 2026-11-19 | BSD-3-Clause (Flagsmith/flagsmith; also the spec's own `info.license`) | "Short-lived access token for the Admin API." (in `c3ef832`), "...for the Management API." (in `f504f16`, the same commit as "feat: rename admin api to management" #8464): 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.

Expand All @@ -54,3 +56,5 @@ The PlanetScale copies are trimmed by lines: everything before `paths:` (`openap
The Appwrite copies keep `openapi`, `info`, `servers` and the path items involved, whole and in their original order; `tags`, `components` and `externalDocs` left out. They're re-serialized the way the originals are written (4-space indent, `/` written `\/`, non-ASCII as `\u` escapes), which gives every original line back byte for byte when nothing is left out, so every kept line is unchanged bar a trailing comma. The 1.9.x pair keeps the paths of the 14 operations deprecated in `7d74bf9f`, the 2.4.x pair the paths of the 13 operations that lost the server platform in `06e6fafa`, the 1.7.x and 1.8.x pair the paths of the 21 operations flagged only for an SDK method rename. With the full files the plugin gives the same results: 14 events, none, and none (50, from the rest of 1.8.x's Databases deprecations, with the 21 renames still left out).

Stripe's spec isn't saved here: its tests use small specs written inline.

The Flagsmith copies are trimmed by lines: `openapi`, `info` and `servers`, then the path items involved (`paths: {}` where none remain, the one line in `v2.287.0.yaml` that isn't in the original) and, under `components: schemas:`, every schema those paths' request bodies reach, transitively, whole and in original order, every line copied unchanged; `tags` and `security` left out. `FeatureValue`, `FeatureValueTypeEnum` and `MultivariateValue` are kept unchanged in both files because the real spec still has them at `v2.287.0` (other, unremoved operations use them too); every other schema the removed paths reached (`DeleteSegmentOverride`, `EnvironmentDefault`, `FeatureIdentifier`, `FeatureUpdateSegmentData`, `SegmentIdentifier`, `SegmentOverride`, `UpdateFlag`, `UpdateFlagV2`) really is gone in `v2.287.0`, confirmed against the full file. The drop-test pair is two commits, not tags, kept whole but for the same trim (`TokenExchangeResponse` and the `Master API Key` security scheme, the only two places that commit touched `openapi.yaml`).
36 changes: 36 additions & 0 deletions plugins/openapi/testdata/flagsmith-desc-c3ef832.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
openapi: 3.1.0
info:
title: Flagsmith API
version: v1
description: 'Flagsmith''s Core and SDK APIs. Check out <a href=''https://docs.flagsmith.com''>Flagsmith documentation</a>.'
contact:
email: [email protected]
license:
name: BSD License
identifier: BSD-3-Clause
servers:
- url: 'https://api.flagsmith.com'
description: Flagsmith API
paths: {}
components:
schemas:
TokenExchangeResponse:
type: object
properties:
access_token:
description: Short-lived access token for the Admin API.
type: string
token_type:
description: Always "Bearer".
type: string
expires_in:
description: Access token lifetime in seconds.
type: integer
required:
- access_token
securitySchemes:
Master API Key:
type: apiKey
in: header
name: Authorization
description: 'For Admin API endpoints. <a href=''https://docs.flagsmith.com/clients/rest#private-api-endpoints''>Find out more</a>.'
36 changes: 36 additions & 0 deletions plugins/openapi/testdata/flagsmith-desc-f504f16.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
openapi: 3.1.0
info:
title: Flagsmith API
version: v1
description: 'Flagsmith''s Core and SDK APIs. Check out <a href=''https://docs.flagsmith.com''>Flagsmith documentation</a>.'
contact:
email: [email protected]
license:
name: BSD License
identifier: BSD-3-Clause
servers:
- url: 'https://api.flagsmith.com'
description: Flagsmith API
paths: {}
components:
schemas:
TokenExchangeResponse:
type: object
properties:
access_token:
description: Short-lived access token for the Management API.
type: string
token_type:
description: Always "Bearer".
type: string
expires_in:
description: Access token lifetime in seconds.
type: integer
required:
- access_token
securitySchemes:
Master API Key:
type: apiKey
in: header
name: Authorization
description: 'For Management API endpoints. <a href=''https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/management-api''>Find out more</a>.'
Loading
Loading