feat(sdks): add isomorphic spec platform#12346
Conversation
Adds an `isomorphic` virtual SDK platform whose spec is the union of the `client` and `server` specs. Lets a single SDK release (e.g. the web SDK) surface methods from both runtimes — including ones that are hidden from the `server` spec or auth-excluded from it. - `APP_SDK_PLATFORM_ISOMORPHIC` constant - Specs.php emits `swagger2-<v>-isomorphic.json` (and OpenAPI3) using a union filter; `getKeys()` / `getAuthCounts()` extended accordingly - SDKs.php honors an optional `specPlatform` per-SDK config override so a server-family SDK can point at the isomorphic spec - Format/Swagger2 + OpenAPI3 use a shared `effectivePlatforms()` helper so the additional-methods filter expands isomorphic to client+server, preserving rename pairs like `createMfaAuthenticator` ↔ `createMFAAuthenticator`
Greptile SummaryThis PR introduces an
Confidence Score: 3/5The change is generally well-structured, but authCount = 1 for the isomorphic platform causes array_slice to drop the JWT entry from x-appwrite.auth on every server-side route in the isomorphic spec. The route-filtering and key-union logic look correct, and the author's manual verification (606 ops = 602 + 4) lines up with expectations. The one concrete defect is authCount = 1: the server spec deliberately uses 2 so that both Key and JWT appear in x-appwrite.auth for server routes; with 1, JWT is silently truncated from every server-side route's auth metadata in the isomorphic spec, which could cause the SDK generator to omit JWT auth constructors for those methods. src/Appwrite/Platform/Tasks/Specs.php — specifically the getAuthCounts() value for the isomorphic platform and its stale type annotations. Important Files Changed
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| 'client' => 1, | ||
| 'server' => 2, | ||
| 'console' => 1, | ||
| APP_SDK_PLATFORM_ISOMORPHIC => 1, |
There was a problem hiding this comment.
authCount for isomorphic is set to 1, matching the client's value, but the server platform uses 2 to expose both Key and JWT in x-appwrite.auth. Since the isomorphic spec includes server-side routes (whose $securities will contain both Key and JWT), array_slice($securities, 0, 1) silently drops the JWT entry from every server route's x-appwrite.auth extension. If the SDK generator reads that extension to decide which auth constructors to emit, the isomorphic SDK would lose JWT support for server-side operations — a regression compared to generating directly against the server spec.
| APP_SDK_PLATFORM_ISOMORPHIC => 1, | |
| APP_SDK_PLATFORM_ISOMORPHIC => 2, |
✨ Benchmark resultsComparing 1.9.x (before) to feat/isomorphic-spec-platform (after). Before
After
Delta
Top API waits
|
1 participant
Summary
Adds a virtual
isomorphicSDK platform whose spec is the union of the existingclientandserverspecs. This lets a single SDK release (concretely: the web SDK) surface methods from both runtimes — including ones that are hidden from theserverspec or auth-excluded from it.Motivation: the upcoming isomorphic Web SDK (sdk-generator #1512) targets
--platform=serverbut needs to keep all the methods previously shipped on the client side (e.g.account.createOAuth2Session,account.createPushTarget/update/delete) so existing browser callers don't regress. Without this PR, generating the web SDK against--platform=serverdrops those methods because they're hidden from / auth-excluded from the server spec.Changes
APP_SDK_PLATFORM_ISOMORPHIC = 'isomorphic'constantSpecs.phpgetPlatforms(),getKeys()(union of client + server keys),getAuthCounts()effectivePlatformsFor()helper that expandsisomorphicto[client, server]; legacy single-platform behavior is preservedSDKs.phpspecPlatformconfig field per SDK; falls back tofamily. Lets aserver-family SDK consume theisomorphicspec without changing its rendering familyFormat.php(base) —effectivePlatforms()helperFormat/Swagger2.php,Format/OpenAPI3.php— useeffectivePlatforms()in the additional-methods filter so rename pairs likecreateMfaAuthenticator↔createMFAAuthenticatorcontinue to surface in the isomorphic specVerification
Regenerated specs and the web SDK locally with
specPlatform: isomorphicon a server-familywebSDK config:swagger2-1.9.x-isomorphic.jsoncontains 606 operations (= server's 602 + the four client-onlyaccount.createOAuth2Session/createPushTarget/updatePushTarget/deletePushTarget)server-web/against the liveappwrite/sdk-for-webmainbranch shows zero method removalscreateMfaAuthenticator+createMFAAuthenticator, etc.) both appear in the generated outputTest plan
php app/cli.php specs --version=1.9.x --git=noproduces a non-emptyswagger2-1.9.x-isomorphic.jsonwhose operation count ≥ server spec'sspecPlatform => APP_SDK_PLATFORM_ISOMORPHICconsumes that spec correctly