Skip to content

add the appwrite plugin - #135

Merged
brandonphelps1212 merged 4 commits into
mainfrom
appwrite-plugin
Nov 20, 2026
Merged

brandonphelps1212 merged 4 commits into
mainfrom
appwrite-plugin

Conversation

@brandonphelps1212

Copy link
Copy Markdown
Contributor

What this changes

Adds appwrite, an openapi plugin for Appwrite's server API. Part of #76 (I11.8 · Watch Appwrite), under #14.

  • Source: https://github.com/appwrite/specs (BSD-3-Clause). It reads the newest specs/<X.Y>.x directory (compared by number), pinned to a commit SHA.

    • From 2.0.x on, that's the single document filtered to operations whose x-appwrite.platforms include server.
    • Up to 1.9.x, it's open-api3-<X.Y>.x-server.json.
    • appwrite/appwrite stopped tracking its specs after 1.8.1.
  • version is the pinned commit's date (UTC), like neon, convex and planetscale. Appwrite's server version (info.version, e.g. 1.9.5) isn't what a repo pins: the SDKs are numbered on their own (node-appwrite 32.x). The client gets appwrite in its date-versioned list in a separate PR.

  • Operation names include /v1, via the shared adapter.ServerBasePath. Quotes point into the spec as published.

  • Rule: deprecations only, never removals. Of the removals in the history, only one was marked deprecated first, and it was a path move still served through an alias. A deprecation is the deprecated flag, quoted as x-appwrite.deprecated ({since, replaceWith}), because the descriptions don't say why.

  • New shared diff.Options, with zero values leaving every other golden unchanged:

    • QuoteDeprecated: what a flag deprecation cites, relative to the operation.
    • FlagNotDeprecation(op): a flag that isn't a route deprecation.

    For Appwrite, that's an SDK method rename (replaceWith names another method of the same operation, e.g. Mfa → MFA), or an operation where any SDK method is still live.

  • Fails loudly: if filtering to server leaves no operations (say, if the layout changes), Fetch errors instead of emitting nothing.

  • History: replaying all 177 commits, side branches and every directory switch included, gives exactly 14 events. They're the deprecations of 2026-06-24: the six /v1/databases/transactions operations and the text/varchar attribute operations, each replaced by tablesDB.*.

Needs a client change

appwrite must be added to the patch-it client's list of date-versioned APIs. It's included in the client PR that adds neon, convex and planetscale.

Checklist

  • Added to docs/plugins.md: new row, status live. docs/plugins.json regenerated, README badge 28. I compared the row's words with the plugin.
  • Every commit is signed off (DCO)
  • Golden test: 1.9.x server spec, 8c00ba35 → 7d74bf9f, 14 deprecation events.
  • Pinned drop test: 2.4.x 98cc1a25 → 06e6fafa, 0 events. With the filter off it gives 13 removals: operations taken off server for a day, which came back in 2.5.x.
  • Rename filter test: 1.7.x → 1.8.x method renames give 0 events (21 without the filter). On the full files, 50 of 71 new flags are kept, the Databases → TablesDB deprecations.
  • Tests for the live-method rule and the zero-operations error.
  • testdata/README.md rows: URL at the commit, date, license (BSD-3-Clause), quote. The fixtures are re-serialized; on a full file that reproduces the original byte for byte, as documented.
  • providers/appwrite.md from the template, with Why this source and Known gaps (unmarked removals, whose real ones are in the SDK changelogs; specs commits that don't line up with releases).
  • Fetches only through the fetch layer.
  • make check passes.
  • Nothing private.

Notes for the reviewer

An independent review replayed the specs repo through the branch's own adapter.

  • All 177 commits give only the 14.
  • The rename filter drops only real renames: the 23 case renames in 2.7.x, never a route deprecation.
  • 10 of 11 mutations it tried make a test fail. The survivor is harmless.

Its findings are fixed in the last commit: date versions so the client doesn't drop the events, /v1 paths, the live-method rule, and the zero-operations error.

🤖 Generated with Claude Code

brandonphelps1212 and others added 3 commits November 19, 2026 19:28
Watches appwrite/specs (the newest minor's server operations at the newest
commit) for operation deprecations, quoting x-appwrite.deprecated. SDK method
renames flagged deprecated are not read as deprecations, and removals are
never events. Adds two diff options, QuoteDeprecated and FlagNotDeprecation;
their zero values keep every other plugin's output unchanged.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: brandonphelps1212 <[email protected]>
Keeps both sides of the shared files: the neon, convex and planetscale rows and registrations, then appwrite's.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: brandonphelps1212 <[email protected]>
Version is the specs commit's date, for the client's date-versioned gate:
a server version can't be placed against an SDK pin. Operations are named
by the path a caller sends (/v1/...) through ServerBasePath, with pointers
into the spec as published. A deprecated flag on an operation that still
has a live SDK method isn't read as a deprecation, and a single document
with no server operation fails the fetch.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: brandonphelps1212 <[email protected]>
@claude

claude Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Claude finished @brandonphelps1212's task in 2m 4s —— View job


✅ Ready to merge. The plugin follows every repo rule, all local checks pass, and I found no path that emits an event for something that isn't a real deprecation.

Rules

Rule Status Evidence
Plugin list (Rule 1) ✅ The appwrite row is between the markers, with absolute links and status live. Its words match the code: openapi, server operations, deprecations only, renames left out. docs/plugins.json and the badge (28) are regenerated. go test passes, so the json is up to date.
Provider page ✅ providers/appwrite.md follows the template. Why this source has the link, the date checked (2026-11-19), why it's the best source, four alternatives not used (appwrite/appwrite app/config/specs, the SDK changelogs, the deprecations page, the changelog/RSS) and a quote. It also has an index row in providers/README.md.
Golden test + quote ✅ TestAppwriteGolden: 1.9.x 8c00ba35 → 7d74bf9f gives 14 deprecations. Each one quotes x-appwrite.deprecated, and the test checks the quote against the node in the saved file, with the pointer mapped back to the path as published (no /v1). There are testdata/README.md rows for all three pairs (URL at the commit, date, BSD-3-Clause, quote), and the trimming is explained.
Drop test ✅ TestAppwriteDropsRemovals: 2.4.x 98cc1a25 → 06e6fafa gives 0 events, and 13 removals without the filter. There's also a second drop test for SDK renames: 0 events, 21 without FlagNotDeprecation.
Fetch only via env ✅ adapter/appwrite.go goes only through fetch.Get. There's no net/http outside tests, and no filesystem or database access.
Contract fixtures ✅ Unchanged.
Nothing private (Rule 2) ✅ I found nothing private in the code, docs, test data, commit messages or the PR body. The leak guard is clean. Every commit is signed off.

Bugs

None found. What I checked:

  • The diff changes leave other plugins alone. With their zero values, flagDeprecated is the same as the old truthy(op["deprecated"]), and the new QuoteDeprecated branch only runs when that option is set. Every other golden is unchanged.
  • The 2.0.x+ server filter (appwriteServerOnly). It drops methods without server and drops path items left with no operation. If no operation is left at all, it errors instead of returning an empty spec, which would silently read as "nothing deprecated". This is the right call for precision.
  • appwriteMethodLevel. It runs on both the old and the new operation. So a rename-only flag never counts, and the same operation becoming deprecated for real later is still an event. Tests cover the edge cases: deprecated: false, no methods, a missing x-appwrite.
  • newestAppwriteDir. It compares minors by number (2.10 is newer than 2.9) and skips latest.

Verified

  • go build ./...: ok
  • go vet ./...: no output
  • gofmt -l .: no output
  • go test -race ./...: every package passes, including plugins/openapi, diff, adapter and internal/pluginlist
  • python3 scripts/leak_guard.py --all: "no banned terms (8 hashed terms checked)"
  • git log: all 3 PR commits have Signed-off-by and the co-author trailer

I didn't run make contract, because no patch-it checkout is available here. This PR doesn't touch contract/fixtures/.

Non-blocking

  • providers/appwrite.md:46 (inline comment): the "Known gaps" line says deprecations that come with a new minor's directory aren't events. In fact, when the newest minor changes, the plugin diffs the new directory against the previous minor's last spec, so an operation that was unflagged before and is flagged now is an event. Only operations that first appear already flagged are missed. This is a wording fix only.
  • Merging still depends on the client PR that adds appwrite to the date-versioned APIs. Until that's in, the client would drop these events. The PR body and the provider page both say so; it's just worth merging the two together.

Nice work: the history replay and the tests on what the filter keeps and drops make this easy to trust.

Comment thread providers/appwrite.md Outdated
## Known gaps

- **Removals aren't events.** The spec doesn't mark them first, so real ones are missed. The SDK changelogs say them ("* Breaking: removed `X`"); a `changelog` plugin per SDK could read them.
- **Deprecations from before the plugin's first run aren't events,** nor ones that came with a new minor's directory already flagged. The Databases to TablesDB deprecations of 1.8.0 can be replayed (`1.7.x@<sha>` to `<sha>`), and a run never sees them.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Non-blocking, wording only: I don't think "nor ones that came with a new minor's directory already flagged" matches the code. When a new specs/<X.Y>.x appears, Fetch switches to it and the plugin diffs it against the last spec it saw from the previous minor. So an operation that was unflagged in 2.7.x and is flagged in a new 2.8.x is an event. The 1.7.x → 1.8.x replay shows this: 50 events. What's actually missed is an operation that is new in the new minor and already flagged, because it has no unflagged version to compare against. Could you reword this, e.g. "nor operations that first appear already flagged (for example in a new minor's directory)"?

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: brandonphelps1212 <[email protected]>
@brandonphelps1212
brandonphelps1212 merged commit e89b669 into main Nov 20, 2026
4 checks passed
@brandonphelps1212
brandonphelps1212 deleted the appwrite-plugin branch November 20, 2026 00:52
@brandonphelps1212 brandonphelps1212 mentioned this pull request Nov 20, 2026
15 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant