diff --git a/README.md b/README.md index d17a116..7cb71bc 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-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) diff --git a/adapter/flagsmith.go b/adapter/flagsmith.go new file mode 100644 index 0000000..b491d8e --- /dev/null +++ b/adapter/flagsmith.go @@ -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 +} diff --git a/docs/plugins.json b/docs/plugins.json index b3fc203..eebb26f 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": 28, + "count": 29, "plugins": [ { "id": "algolia-ingestion", @@ -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", diff --git a/docs/plugins.md b/docs/plugins.md index d1a32c4..a01d7e4 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -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/open-api3-.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 | ## The columns diff --git a/plugins/openapi/flagsmith_test.go b/plugins/openapi/flagsmith_test.go new file mode 100644 index 0000000..3cce606 --- /dev/null +++ b/plugins/openapi/flagsmith_test.go @@ -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", + }, 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)) + } +} diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index 5fca822..3d943d6 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -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 diff --git a/plugins/openapi/testdata/README.md b/plugins/openapi/testdata/README.md index b03e3cf..2e5210d 100644 --- a/plugins/openapi/testdata/README.md +++ b/plugins/openapi/testdata/README.md @@ -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. @@ -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`). diff --git a/plugins/openapi/testdata/flagsmith-desc-c3ef832.yaml b/plugins/openapi/testdata/flagsmith-desc-c3ef832.yaml new file mode 100644 index 0000000..3bc764e --- /dev/null +++ b/plugins/openapi/testdata/flagsmith-desc-c3ef832.yaml @@ -0,0 +1,36 @@ +openapi: 3.1.0 +info: + title: Flagsmith API + version: v1 + description: 'Flagsmith''s Core and SDK APIs. Check out Flagsmith documentation.' + contact: + email: support@flagsmith.com + 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. Find out more.' diff --git a/plugins/openapi/testdata/flagsmith-desc-f504f16.yaml b/plugins/openapi/testdata/flagsmith-desc-f504f16.yaml new file mode 100644 index 0000000..82857f9 --- /dev/null +++ b/plugins/openapi/testdata/flagsmith-desc-f504f16.yaml @@ -0,0 +1,36 @@ +openapi: 3.1.0 +info: + title: Flagsmith API + version: v1 + description: 'Flagsmith''s Core and SDK APIs. Check out Flagsmith documentation.' + contact: + email: support@flagsmith.com + 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. Find out more.' diff --git a/plugins/openapi/testdata/flagsmith-v2.286.0.yaml b/plugins/openapi/testdata/flagsmith-v2.286.0.yaml new file mode 100644 index 0000000..c5e475f --- /dev/null +++ b/plugins/openapi/testdata/flagsmith-v2.286.0.yaml @@ -0,0 +1,309 @@ +openapi: 3.1.0 +info: + title: Flagsmith API + version: v1 + description: 'Flagsmith''s Core and SDK APIs. Check out Flagsmith documentation.' + contact: + email: support@flagsmith.com + license: + name: BSD License + identifier: BSD-3-Clause +servers: + - url: 'https://api.flagsmith.com' + description: Flagsmith API +paths: + '/api/experiments/environments/{environment_key}/delete-segment-override/': + post: + operationId: api_experiments_environments_delete_segment_override_create + summary: Delete segment override + description: |2- + + **EXPERIMENTAL ENDPOINT** - Subject to change without notice. + + Deletes a segment override for a feature in the given environment. + + **Feature Identification:** + - Use `feature.name` OR `feature.id` (mutually exclusive) + - Feature must belong to the environment's project + + **Segment Identification:** + - Use `segment.id` (required) + + The segment override must exist for the given feature/environment combination. + Returns 400 if the segment override does not exist. + + parameters: + - name: environment_key + in: path + description: The environment API key + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteSegmentOverride' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/DeleteSegmentOverride' + multipart/form-data: + schema: + $ref: '#/components/schemas/DeleteSegmentOverride' + responses: + '204': + description: No response body + security: + - tokenAuth: [] + - Master API Key: [] + tags: + - experimental + '/api/experiments/environments/{environment_key}/update-flag-v1/': + post: + operationId: api_experiments_environments_update_flag_v1_create + summary: Update single feature state + description: |2- + + **EXPERIMENTAL ENDPOINT** - Subject to change without notice. + + Updates a single feature state within an environment. You can update either: + - The environment default state (when no segment is specified) + - A specific segment override (when segment.id is provided) + + **Feature Identification:** + - Use `feature.name` OR `feature.id` (mutually exclusive) + + **Value Format:** + - The `value` field is always a string representation + - The `type` field tells the server how to parse it + - Available types: integer, string, boolean + - Examples: + - `{"type": "integer", "value": "42"}` + - `{"type": "boolean", "value": "true"}` + - `{"type": "string", "value": "hello"}` + + **Segment Priority:** + - Optional `segment.priority` field controls ordering + - If field value is null or the field is omitted, lowest priority is assumed + + parameters: + - name: environment_key + in: path + description: The environment API key + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateFlag' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/UpdateFlag' + multipart/form-data: + schema: + $ref: '#/components/schemas/UpdateFlag' + responses: + '204': + description: No response body + security: + - tokenAuth: [] + - Master API Key: [] + tags: + - experimental + '/api/experiments/environments/{environment_key}/update-flag-v2/': + post: + operationId: api_experiments_environments_update_flag_v2_create + summary: Update multiple feature states + description: |2- + + **EXPERIMENTAL ENDPOINT** - Subject to change without notice. + + Updates multiple feature states in a single request. This endpoint allows + you to configure an entire feature (environment default + all segment overrides) + in one operation. + + **What You Can Update:** + - Environment default state (required) + - Multiple segment overrides (optional) + - Priority ordering for each segment + + **Feature Identification:** + - Use `feature.name` OR `feature.id` (mutually exclusive) + + **Value Format:** + - The `value` field is always a string representation + - The `type` field tells the server how to parse it + - Available types: integer, string, boolean + - Examples: + - `{"type": "string", "value": "production"}` + - `{"type": "integer", "value": "100"}` + - `{"type": "boolean", "value": "false"}` + + **Segment Overrides:** + - Provide array of segment override configurations + - Each override must specify: segment_id, enabled, value + - Optional priority field controls ordering + - Duplicate segment_id values are not allowed + + + parameters: + - name: environment_key + in: path + description: The environment API key + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateFlagV2' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/UpdateFlagV2' + multipart/form-data: + schema: + $ref: '#/components/schemas/UpdateFlagV2' + responses: + '204': + description: No response body + security: + - tokenAuth: [] + - Master API Key: [] + tags: + - experimental +components: + schemas: + DeleteSegmentOverride: + type: object + properties: + feature: + $ref: '#/components/schemas/FeatureIdentifier' + segment: + $ref: '#/components/schemas/SegmentIdentifier' + required: + - feature + - segment + EnvironmentDefault: + type: object + properties: + enabled: + type: boolean + value: + $ref: '#/components/schemas/FeatureValue' + required: + - enabled + - value + FeatureIdentifier: + type: object + properties: + name: + type: string + id: + type: integer + FeatureUpdateSegmentData: + type: object + properties: + id: + type: integer + priority: + type: + - integer + - 'null' + required: + - id + FeatureValue: + type: object + properties: + type: + $ref: '#/components/schemas/FeatureValueTypeEnum' + value: + type: string + required: + - type + - value + FeatureValueTypeEnum: + description: |- + * `integer` - integer + * `string` - string + * `boolean` - boolean + type: string + enum: + - integer + - string + - boolean + MultivariateValue: + type: object + properties: + multivariate_feature_option: + type: integer + percentage_allocation: + type: number + format: double + maximum: 100 + minimum: 0 + required: + - multivariate_feature_option + - percentage_allocation + SegmentIdentifier: + type: object + properties: + id: + type: integer + required: + - id + SegmentOverride: + type: object + properties: + segment_id: + type: integer + priority: + type: + - integer + - 'null' + enabled: + type: boolean + value: + $ref: '#/components/schemas/FeatureValue' + multivariate_feature_state_values: + type: array + items: + $ref: '#/components/schemas/MultivariateValue' + required: + - enabled + - segment_id + - value + UpdateFlag: + type: object + properties: + feature: + $ref: '#/components/schemas/FeatureIdentifier' + segment: + $ref: '#/components/schemas/FeatureUpdateSegmentData' + enabled: + type: boolean + value: + $ref: '#/components/schemas/FeatureValue' + required: + - enabled + - feature + - value + UpdateFlagV2: + type: object + properties: + feature: + $ref: '#/components/schemas/FeatureIdentifier' + environment_default: + $ref: '#/components/schemas/EnvironmentDefault' + segment_overrides: + type: array + items: + $ref: '#/components/schemas/SegmentOverride' + required: + - environment_default + - feature diff --git a/plugins/openapi/testdata/flagsmith-v2.287.0.yaml b/plugins/openapi/testdata/flagsmith-v2.287.0.yaml new file mode 100644 index 0000000..2bd391c --- /dev/null +++ b/plugins/openapi/testdata/flagsmith-v2.287.0.yaml @@ -0,0 +1,49 @@ +openapi: 3.1.0 +info: + title: Flagsmith API + version: v1 + description: 'Flagsmith''s Core and SDK APIs. Check out Flagsmith documentation.' + contact: + email: support@flagsmith.com + license: + name: BSD License + identifier: BSD-3-Clause +servers: + - url: 'https://api.flagsmith.com' + description: Flagsmith API +paths: {} +components: + schemas: + FeatureValue: + type: object + properties: + type: + $ref: '#/components/schemas/FeatureValueTypeEnum' + value: + type: string + required: + - type + - value + FeatureValueTypeEnum: + description: |- + * `integer` - integer + * `string` - string + * `boolean` - boolean + type: string + enum: + - integer + - string + - boolean + MultivariateValue: + type: object + properties: + multivariate_feature_option: + type: integer + percentage_allocation: + type: number + format: double + maximum: 100 + minimum: 0 + required: + - multivariate_feature_option + - percentage_allocation diff --git a/plugins/openapi/testdata/golden/flagsmith.json b/plugins/openapi/testdata/golden/flagsmith.json new file mode 100644 index 0000000..0eccaac --- /dev/null +++ b/plugins/openapi/testdata/golden/flagsmith.json @@ -0,0 +1,65 @@ +[ + { + "id": 1, + "fingerprint": "sha256:9d8954a4311788d780d04796043dc3382369ea6856663403d91e0622ee46440b", + "api": "flagsmith", + "version": "2.287.0", + "previous_version": "2.286.0", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /api/experiments/environments/{environment_key}/delete-segment-override/" + }, + "description": "Operation POST /api/experiments/environments/{environment_key}/delete-segment-override/ removed.", + "source_url": "https://raw.githubusercontent.com/Flagsmith/flagsmith/v2.286.0/openapi.yaml", + "source_pointer": "/paths/~1api~1experiments~1environments~1{environment_key}~1delete-segment-override~1/post", + "source_excerpt": "{\"description\":\"\\n **EXPERIMENTAL ENDPOINT** - Subject to change without notice.\\n\\n Deletes a segment override for a feature in the given environment.\\n\\n **Feature Identification:**\\n - Use `feature.name` OR `feature.id` (mutually exclusive)\\n - Feature must belong to the environment's project\\n\\n **Segment Identification:**\\n - Use `segment.id` (required)\\n\\n The segment override must exist for the given feature/environment combination.\\n Returns 400 if the segment override does not exist.\\n \",\"operationId\":\"api_experiments_environments_delete_segment_override_create\",\"parameters\":[{\"description\":\"The environment API key\",\"in\":\"path\",\"name\":\"environment_key\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/DeleteSegmentOverride\"}},\"application/x-www-form-urlencoded\":{\"schema\":{\"$ref\":\"#/components/schemas/DeleteSegmentOverride\"}},\"multipart/form-data\":{\"schema\":{\"$ref\":\"#/components/schemas/DeleteSegmentOverride\"}}},\"required\":true},\"responses\":{\"204\":{\"description\":\"No response body\"}},\"security\":[{\"tokenAuth\":[]},{\"Master API Key\":[]}],\"summary\":\"Delete segment override\",\"tags\":[\"experimental\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 2, + "fingerprint": "sha256:679f551f2accf69eb0af557218cc8c0ae617589fea24835cc12b9358e4b4b644", + "api": "flagsmith", + "version": "2.287.0", + "previous_version": "2.286.0", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /api/experiments/environments/{environment_key}/update-flag-v1/" + }, + "description": "Operation POST /api/experiments/environments/{environment_key}/update-flag-v1/ removed.", + "source_url": "https://raw.githubusercontent.com/Flagsmith/flagsmith/v2.286.0/openapi.yaml", + "source_pointer": "/paths/~1api~1experiments~1environments~1{environment_key}~1update-flag-v1~1/post", + "source_excerpt": "{\"description\":\"\\n **EXPERIMENTAL ENDPOINT** - Subject to change without notice.\\n\\n Updates a single feature state within an environment. You can update either:\\n - The environment default state (when no segment is specified)\\n - A specific segment override (when segment.id is provided)\\n\\n **Feature Identification:**\\n - Use `feature.name` OR `feature.id` (mutually exclusive)\\n\\n **Value Format:**\\n - The `value` field is always a string representation\\n - The `type` field tells the server how to parse it\\n - Available types: integer, string, boolean\\n - Examples:\\n - `{\\\"type\\\": \\\"integer\\\", \\\"value\\\": \\\"42\\\"}`\\n - `{\\\"type\\\": \\\"boolean\\\", \\\"value\\\": \\\"true\\\"}`\\n - `{\\\"type\\\": \\\"string\\\", \\\"value\\\": \\\"hello\\\"}`\\n\\n **Segment Priority:**\\n - Optional `segment.priority` field controls ordering\\n - If field value is null or the field is omitted, lowest priority is assumed\\n \",\"operationId\":\"api_experiments_environments_update_flag_v1_create\",\"parameters\":[{\"description\":\"The environment API key\",\"in\":\"path\",\"name\":\"environment_key\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/UpdateFlag\"}},\"application/x-www-form-urlencoded\":{\"schema\":{\"$ref\":\"#/components/schemas/UpdateFlag\"}},\"multipart/form-data\":{\"schema\":{\"$ref\":\"#/components/schemas/UpdateFlag\"}}},\"required\":true},\"responses\":{\"204\":{\"description\":\"No response body\"}},\"security\":[{\"tokenAuth\":[]},{\"Master API Key\":[]}],\"summary\":\"Update single feature state\",\"tags\":[\"experimental\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 3, + "fingerprint": "sha256:f787d4463ba4f53083c9ebf3e686f3668606c61d8501c4256ebc4ad87a444668", + "api": "flagsmith", + "version": "2.287.0", + "previous_version": "2.286.0", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /api/experiments/environments/{environment_key}/update-flag-v2/" + }, + "description": "Operation POST /api/experiments/environments/{environment_key}/update-flag-v2/ removed.", + "source_url": "https://raw.githubusercontent.com/Flagsmith/flagsmith/v2.286.0/openapi.yaml", + "source_pointer": "/paths/~1api~1experiments~1environments~1{environment_key}~1update-flag-v2~1/post", + "source_excerpt": "{\"description\":\"\\n **EXPERIMENTAL ENDPOINT** - Subject to change without notice.\\n\\n Updates multiple feature states in a single request. This endpoint allows\\n you to configure an entire feature (environment default + all segment overrides)\\n in one operation.\\n\\n **What You Can Update:**\\n - Environment default state (required)\\n - Multiple segment overrides (optional)\\n - Priority ordering for each segment\\n\\n **Feature Identification:**\\n - Use `feature.name` OR `feature.id` (mutually exclusive)\\n\\n **Value Format:**\\n - The `value` field is always a string representation\\n - The `type` field tells the server how to parse it\\n - Available types: integer, string, boolean\\n - Examples:\\n - `{\\\"type\\\": \\\"string\\\", \\\"value\\\": \\\"production\\\"}`\\n - `{\\\"type\\\": \\\"integer\\\", \\\"value\\\": \\\"100\\\"}`\\n - `{\\\"type\\\": \\\"boolean\\\", \\\"value\\\": \\\"false\\\"}`\\n\\n **Segment Overrides:**\\n - Provide array of segment override configurations\\n - Each override must specify: segment_id, enabled, value\\n - Optional priority field controls ordering\\n - Duplicate segment_id values are not allowed\\n\\n \",\"operationId\":\"api_experiments_environments_update_flag_v2_create\",\"parameters\":[{\"description\":\"The environment API key\",\"in\":\"path\",\"name\":\"environment_key\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/UpdateFlagV2\"}},\"application/x-www-form-urlencoded\":{\"schema\":{\"$ref\":\"#/components/schemas/UpdateFlagV2\"}},\"multipart/form-data\":{\"schema\":{\"$ref\":\"#/components/schemas/UpdateFlagV2\"}}},\"required\":true},\"responses\":{\"204\":{\"description\":\"No response body\"}},\"security\":[{\"tokenAuth\":[]},{\"Master API Key\":[]}],\"summary\":\"Update multiple feature states\",\"tags\":[\"experimental\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + } +] diff --git a/providers/README.md b/providers/README.md index 7a00e40..b3bbcae 100644 --- a/providers/README.md +++ b/providers/README.md @@ -36,5 +36,6 @@ One page per plugin id: `providers/.md`. Start from [`_template.md`](_templ | [redis.md](redis.md) | `redis` | `catalog` | | [cloudflare.md](cloudflare.md) | `cloudflare` | `feed` | | [mongodb-atlas.md](mongodb-atlas.md) | `mongodb-atlas` | `apichangelog` | +| [flagsmith.md](flagsmith.md) | `flagsmith` | `openapi` | The list of plugins, with their status, is [docs/plugins.md](../docs/plugins.md). diff --git a/providers/flagsmith.md b/providers/flagsmith.md new file mode 100644 index 0000000..ac87987 --- /dev/null +++ b/providers/flagsmith.md @@ -0,0 +1,37 @@ +# Flagsmith (`flagsmith`) + +## What it watches + +Flagsmith's REST API (the Admin/Management API and the SDK-facing endpoints together) between releases of Flagsmith's own OpenAPI 3.1 spec: whole operations removed, and request parameters callers send that are removed, renamed or newly required. + +Format plugin: `openapi` (`plugins/openapi`), with `adapter.Flagsmith` and a request-side filter (`openapi.Plugin.Keep`, same `requestSide` GitLab uses). + +## Why this source + +- **Source:** `openapi.yaml` at the root of [Flagsmith/flagsmith](https://github.com/Flagsmith/flagsmith), fetched at a release tag (`https://raw.githubusercontent.com/Flagsmith/flagsmith//openapi.yaml`); the newest tag from `releases/latest`. Checked on 2026-11-19. +- **Why this one:** it's generated straight from the Django backend with drf-spectacular (`make generate-full-openapi`) and regenerated on every pull request 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. Flagsmith tags a release on almost every merge to `main` (release-please), so two consecutive tags are usually one pull request apart. +- **Alternatives considered:** + - **`sdk/openapi.yaml`**, the same spec filtered down to the SDK-only endpoints (`openapi-filter-flagsmith-sdk.yml`). Reading the full spec instead covers Admin/Management API removals too (the one real breaking change found, below, is an Admin-API-adjacent endpoint `sdk/openapi.yaml` would have caught as well, but there's no reason to read the narrower copy). + - **A deprecations or sunset page.** Searched docs.flagsmith.com on 2026-11-19 and found none: the [release process page](https://docs.flagsmith.com/platform/release-process) says breaking changes "are announced in advance" and ship with migration guides, but points to GitHub Releases for the actual list, not a dedicated page. + - **The main repo's GitHub Releases / `CHANGELOG.md`.** Release-please categorizes them (Features, Bug Fixes, ⚠ BREAKING CHANGES), but entries are prose feature summaries ("Remove the experimental flag update endpoints"), never a request parameter or symbol name in backticks: `changelog`'s classifier (built for a package's `CHANGELOG.md`) found zero matching bullets across the file's history. + - **The Python SDK** ([flagsmith-python-client](https://github.com/Flagsmith/flagsmith-python-client), PyPI `flagsmith`) **and the JS/TS SDK** ([flagsmith-js-client](https://github.com/Flagsmith/flagsmith-js-client), npm `@flagsmith/flagsmith`, formerly `flagsmith`). Both keep a release-please `CHANGELOG.md` with "⚠ BREAKING CHANGES" sections, checked 2026-11-19: the Python client's say things like "drop Python 3.9 support" and "Restore v3 `OfflineHandler` interface"; the JS client's 3.0.4 entry ("The Edge API will no longer allow for `flagsmith.incrementTrait`, this PR removes it from the SDK") is the one bullet in either file that names a removed symbol in backticks, but its sentence shape ("will no longer allow for X, this PR removes it") doesn't match `changelog`'s plain "Removed `X`" templates either. Neither SDK has a MIGRATION.md or UPGRADING.md. A client-library plugin for either is a separate, future addition (see Known gaps). + - **An RSS or Atom feed.** None found: Flagsmith's own blog and changelog have no feed; `docs.flagsmith.com/releases` is a static page, not a feed. +- **Quote:** `"**EXPERIMENTAL ENDPOINT** - Subject to change without notice."` (every operation removed in the replay fixture, below, carried this in its own `description`). + +## How the provider announces changes + +- **No API version in the path or a header.** `/api/v1/...` is the only prefix, and `v1` hasn't changed; `info.version` in the spec is a fixed `"v1"` that doesn't move between releases (checked 2026-11-19), so the event's `version` is the release tag, not `info.version`. +- **A release on almost every merge to `main`**, via release-please; the spec is regenerated and committed in the same pull request, so it's never stale relative to a tag. +- **No stated deprecation window.** The one real removal found (below) was tagged "EXPERIMENTAL ENDPOINT - Subject to change without notice" from the day it shipped and removed three releases later with no deprecation period; nothing in the spec or the release notes marks an operation `deprecated: true` before removing it. + +## What the plugin reads and ignores + +- **Reads** whole operations removed between two tags, and the request-side changes `diff/` already tracks for every `openapi`-format provider (removed or newly-required parameters and request fields). +- **Drops response-side changes**, same reason as GitLab (`requestSide`): a request body's schema is a named, shared component (`UpdateFlagV2`, `FeatureValue`), not inlined like GitLab's hash-named bodies, so the differ reports its removal as its own "schema removed" change, side `response` by default, whether or not the operations that used it are actually gone. Of the 11 changes between `v2.286.0` and `v2.287.0`, 8 are these schema-level echoes of the 3 real operation removals; the filter drops them and keeps the 3 operations. +- The replay fixture: `v2.286.0` to `v2.287.0` (2026-10-15 to 2026-10-20), where PR [#8736](https://github.com/Flagsmith/flagsmith/pull/8736) ("Remove the experimental flag update endpoints") removed `POST /api/experiments/environments/{environment_key}/delete-segment-override/`, `.../update-flag-v1/` and `.../update-flag-v2/` and their eight request-body schemas, listed under "Features" in the [v2.287.0 release](https://github.com/Flagsmith/flagsmith/releases/tag/v2.287.0). All three were marked experimental from the day they shipped; `/api/__future__/...` is where Flagsmith puts their eventual, stable replacements. + +## Known gaps + +- **The experimental caveat.** The one real removal this plugin has seen is of endpoints Flagsmith itself called "subject to change without notice", not a stable, long-shipped one. It's still a genuine removal a caller of those three endpoints would have hit, and the mechanism (an operation vanishing between two tagged specs) is the same one that would catch a stable endpoint's removal. +- **The Python and JS/TS SDKs aren't watched.** Their `CHANGELOG.md` files don't name removed symbols plainly enough for the `changelog` format plugin (see Alternatives considered); a client-library plugin for either would need its own reader, or a looser classifier. +- **No deprecation signal.** Nothing here reads `deprecated: true` on an operation (none exists yet in Flagsmith's spec to learn the shape from) or any advance notice; only an operation already gone becomes an event.