[pull] master from cube-js:master - #671
Merged
Merged
Conversation
…rence (#11571) * docs: regenerate the Platform API reference from the public OpenAPI spec `api-reference/api.yaml` and the `docs.json` nav are generated from cubejs-enterprise's `open-api-spec-public-v3.1.yaml` by `scripts/extract-api.mjs`. Re-run it so the reference covers the deployment settings endpoints added in cubedevinc/cubejs-enterprise#claude/deployment-settings-api-soozam: GET /api/v1/deployments/{deploymentId}/settings PUT /api/v1/deployments/{deploymentId}/settings The regeneration also picks up spec changes that landed upstream without a docs sync — the staging-environment branch route, the three dbt-sync status/result routes, and the removal of the workbook ai-widget-thread route — because the extractor rewrites both files wholesale from the spec. Nothing here is hand-edited. `api-reference/introduction.mdx` is unchanged: its table is per-tag and the new routes fall under the existing Deployments tag. * docs: re-extract after the upstream summary/shaderConfig fixes, redirect the dropped page - Re-ran `scripts/extract-api.mjs` against the updated public spec. The two `/settings` operations now carry short summaries ("Get deployment settings" / "Update deployment settings") with the prose moved to `description`, so Mintlify stops deriving a sentence-long page title and a ~150-char slug from them. `shaderConfig` and its model enums are gone from the public spec, so they no longer appear in the reference either. - Added a redirect for `/api-reference/workbooks/update-published-dashboard-ai-widget-thread`, which this sync removes from the nav — it was a published page, so without the redirect the URL would start 404ing. The extractor rewrites only the `openapi`-backed nav groups, so a hand-added redirect survives regeneration. `extract-api.mjs --check` now reports the reference up to date. * feat(cube-cli): add `cube spec` for discovering the API at runtime Fetches `/api/v1/spec` — the OpenAPI document the API now serves about itself — so neither a person nor an agent has to guess an endpoint's parameters, and the contract comes from the build being talked to rather than a pinned copy. cube spec # index every operation cube spec settings # filter by method/path/summary/operationId cube spec "deployments/{deploymentId}/settings" --json Bare and filtered runs print a METHOD/PATH/SUMMARY table, which is what a human scanning for an endpoint wants. `--json` prints OpenAPI instead: unfiltered, the whole document, so it can be piped into a generator or a validator; filtered, a still-valid document holding only the matching operations plus the transitive closure of the schemas they reference. That closure is the point of the filter rather than a size optimization. An agent asking "what does this endpoint take?" needs the request body's schema resolved — a bare `$ref` would force it to pull the whole document anyway. On the current API that turns a 238KB answer into a 9KB one that still carries all 19 properties of `UpdateDeploymentInput`, its nested `CspsConfig`, and every enum they reach. The closure runs to a fixpoint over a visited set because the schemas are mutually recursive in places; a naive walk would not terminate. Operations are emitted in verb order rather than the server's key order, and non-operation keys on a path item (`parameters`, `summary`, extensions) are skipped. A pattern that matches nothing exits non-zero with a message rather than printing an empty table, since it almost always means a typo. Tested: unit tests cover operation extraction (verb ordering, non-operation keys ignored), matching across all four fields, and the filtered document (only reachable schemas, self-referential schema terminates, `openapi`/`info`/ `securitySchemes` preserved). Also exercised end to end against the real 106-path document served by a local stub. Docs: `reference/cli.mdx` gains a "Discovering the API" section, and `reference/control-plane-api.mdx` documents the `/api/v1/spec` endpoint. * fix(cube-cli): keep path-level parameters and refuse dangling refs in `cube spec` Two ways the filtered document could be silently wrong. Neither fires against today's spec — it has no path-level `parameters` and no non-schema component refs, both verified — but the output is meant to be consumed unattended by agents and generators, so a quiet truncation is the worst failure mode available. - **Path-level `parameters` were dropped.** OpenAPI lets a path item declare parameters that apply to every operation under it, and only the method keys were copied. For a command whose whole pitch is "an endpoint's full parameter list", losing parameters is the one thing it must not do. They now come along, and their refs are seeded into the schema closure. The test fixture already had this shape and asserted nothing about it; it does now. - **Only `#/components/schemas/` refs were followed.** An operation referencing `#/components/parameters/*`, `responses/*` or `requestBodies/*` would produce a document that still carries the `$ref` but not its target — a validator rejects it, an agent resolves it to nothing. The document is now walked for any `#/components/` ref whose target is missing and the command bails, the same way `extract-api.mjs` hard-fails on dangling refs upstream. Also shortens the README row to match the terse verb lists around it; the explanation already lives in `cli.mdx`'s "Discovering the API" section. Tested: 12 unit tests pass (2 new — path-level parameters survive filtering, dangling refs rejected while a resolvable non-schema ref is accepted), fmt and clippy clean, and re-verified end to end against the real 106-path document. * feat(cube-cli): deployment settings, available versions, and version switching `cube deployments versions <id>` lists the Cube versions a deployment can switch to; `cube deployments settings <id>` reads the whole settings payload; `cube deployments update` gains `--release-channel` / `--release-channel-version` so applying a listed version doesn't need a hand-written `--data` body. The version is validated server-side against the list and the container image is resolved from it, so the CLI has nothing to pin and no way to get the two out of step. Docs: the new endpoint on the Control Plane API page, a version-switching section in the CLI reference, and the regenerated API reference — which also picks up the `/api/v1/spec` endpoint's nav group, retitled from the auto-cleaned "Open Api Spec". * fix(cube-cli): send version changes to the settings endpoint `PUT /api/v1/deployments/{id}` responds with the four-field deployment summary, which carries no version — so `cube deployments update --release-channel-version` printed a body in which the thing that changed was invisible. Route those writes to `/settings`, whose response is the full settings payload. Also trim the README's deployments row back to the terse verb list its neighbours use; the version-format detail already lives in the CLI reference. * refactor(cube-cli): send every deployment update to PUT /api/v1/deployments/:id The separate settings write endpoint is gone — `PUT /:id` now takes the full settings body and responds with the full settings payload — so `update` no longer needs to pick a route based on which flags were passed. Docs follow the same consolidation. * docs(cli): use an operationId in the cube spec filtering example `deployments/{deploymentId}` is a substring of 56 paths in the spec, so as a `cube spec` pattern it emits most of the Deployments surface — the opposite of the narrowing the paragraph below it describes. `updateDeployment` matches the one operation (the matcher concatenates method, path, summary and operationId and does a `contains`). * fix(api-gateway): require an isDevToken claim for the playground bypass `signedWithPlaygroundAuthSecret` unlocks developer affordances — meta members hidden by `public: false` / access policies, generated SQL, pre-aggregation and refresh-key debug info on load responses, request ids in errors. It was set purely from the token having verified against `playgroundAuthSecret`. In Cube Cloud that secret signs every token a deployment mints, including ones handed to end users and to external BI tools, so the signature alone was never evidence that the bearer is a developer. Require an explicit `isDevToken` claim as well; the control plane adds it only for the developer-facing console surfaces and only for users with deployment-manage permissions. devMode is unaffected: every affordance already ORs the flag with `getEnv('devMode')`, so a local `cube dev` server keeps full visibility. The one place reading the flag alone is the `isPlayground` field on Load Request logs, which now marks only developer traffic. Authentication is also unchanged — the claim gates what a playground-signed token may see, not whether it verifies, so `/cubejs-system/v1/*` still accepts any playground-signed token. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018rhtueaPpiVVNkvA5rWv8X * refactor(api-gateway): key the playground bypass on a dev-token scope Reads the grant from `scope` — the array the runtime already uses for per-token grants — instead of a bespoke top-level `isDevToken` claim, so a dev token is described the same way as every other capability a token carries. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018rhtueaPpiVVNkvA5rWv8X * docs: drop the /api/v1/spec section from the control plane API reference The endpoint stays; only its reference section goes. `cube spec` on the CLI page still documents the discovery workflow, and nothing linked to the removed anchor. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018rhtueaPpiVVNkvA5rWv8X --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
See Commits and Changes for more details.
Created by
pull[bot] (v2.0.0-alpha.4)
Can you help keep this open source service alive? 💖 Please sponsor : )