chore(api): sync OpenAPI contract by kong[bot] · Pull Request #5 · Kong/volcano-sdk-ruby

kong · 2026-08-30T07:19:54Z

Summary

Sync the vendored OpenAPI contract from Kong/volcano-hosting@e38d59861444.
Regenerate checked-in client or contract types with this repository's pinned tooling.

API change report

Public API

New Endpoints: 3

GET /projects/{id}/autofix-runs
GET /projects/{id}/autofix-runs/{runId}
POST /projects/{id}/issues/{issueId}/autofix-runs

Deleted Endpoints: None

Modified Endpoints: 20

POST /auth/forgot-password

New header param: x-volcano-client-ip
New header param: x-volcano-proxy-authorization
Responses changed
- New response: 401

POST /auth/logout

New header param: x-volcano-client-ip
New header param: x-volcano-proxy-authorization
Responses changed
- New response: 401

POST /auth/oauth/exchange

New header param: x-volcano-client-ip
New header param: x-volcano-proxy-authorization
Responses changed
- Modified response: 401
  - Description changed from 'Missing or invalid project anon key' to 'Missing or invalid project anon key; or invalid auth proxy metadata'

GET /auth/password-policy

New header param: x-volcano-client-ip
New header param: x-volcano-proxy-authorization
Responses changed
- Modified response: 401
  - Description changed from 'Invalid, missing, or revoked anon key' to 'Invalid, missing, or revoked anon key; or invalid auth proxy metadata'

POST /auth/refresh

New header param: x-volcano-client-ip
New header param: x-volcano-proxy-authorization
Responses changed
- Modified response: 401
  - Description changed from 'Invalid or expired refresh token' to 'Invalid or expired refresh token; or invalid auth proxy metadata'

POST /auth/reset-password

New header param: x-volcano-client-ip
New header param: x-volcano-proxy-authorization
Responses changed
- Modified response: 401
  - Description changed from 'Invalid or expired token' to 'Invalid or expired token; or invalid auth proxy metadata'

POST /auth/signin

New header param: x-volcano-client-ip
New header param: x-volcano-proxy-authorization
Responses changed
- Modified response: 401
  - Description changed from 'Unauthorized - Invalid credentials, invalid/tampered/revoked anon key,
    or account banned/deleted
    ' to 'Unauthorized - Invalid credentials, invalid/tampered/revoked anon key,
    or account banned/deleted; or invalid auth proxy metadata
    '

POST /auth/signup

New header param: x-volcano-client-ip
New header param: x-volcano-proxy-authorization
Responses changed
- Modified response: 401
  - Description changed from 'Unauthorized - Invalid, tampered, revoked, or wrong-project anon key
    ' to 'Unauthorized - Invalid, tampered, revoked, or wrong-project anon key.
    Also returned for invalid, repeated, or under-scoped auth proxy metadata
    (invalid auth proxy metadata).
    '

POST /auth/signup-anonymous

New header param: x-volcano-client-ip
New header param: x-volcano-proxy-authorization
Responses changed
- New response: 401

POST /functions/{functionId}/invoke

Description changed from 'Invoke a function. The function's visibility decides which credentials
may call it, and the function does not run for any other. A private
function answers every credential but a service key exactly as a
missing one, with 404, so its name and id cannot be discovered; an anon
key on an authenticated function gets 403. An SDK calling by name
resolves it first through GET /functions/resolve, which answers that
anon key with 404 instead.

With Service Key (admin/background operations, every visibility):

Use for background jobs, webhooks, cron, admin operations
Function receives payload only (no user context)
Database queries bypass RLS (admin access)

With Auth User Token (user-facing, authenticated or public functions):

Use for user-initiated actions
Includes users from anonymous sign-ins

Function receives payload + __volcano_auth context:

{
  user_id: "uuid",
  email: "user@example.com",
  project_id: "uuid",
  role: "authenticated" or "anonymous"
}

Database queries enforce RLS (user-scoped data)

With Anon Key (public functions only):

Requires anon key permission: functions.invoke
Function must have visibility: public
Function receives payload only (no __volcano_auth)

Transport and CORS:

This operation is the authenticated direct RPC endpoint and always uses the
POST {payload: ...} contract, including for functions whose DNS ingress is
configured in HTTP mode.
The geo-routed DNS ingress is the function's invoke_url. It is on a
different domain from this API, so it cannot be derived from the API host.
RPC-mode DNS ingress accepts POST at /. HTTP-mode DNS ingress accepts GET,
HEAD, POST, PUT, PATCH, and DELETE at / and nested paths.
Direct and RPC-mode CORS preflight advertises POST, OPTIONS. HTTP-mode DNS
preflight advertises GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS.
http_auth_mode: none applies only to public HTTP-mode DNS ingress; this
direct operation always requires a Volcano credential.

Durable functions are not invocable here. A durable function's id
answers 404, whatever its visibility, because a synchronous call would
run it with no execution record, no idempotency and no concurrency
accounting. Start one with
POST /durable-functions/{functionId}/executions.
' to 'Invoke a function. The function's visibility decides which credentials
may call it, and the function does not run for any other. A private
function answers every credential but a service key exactly as a
missing one, with 404, so its name and id cannot be discovered; an anon
key on an authenticated function gets 403. An SDK calling by name
resolves it first through GET /functions/resolve, which answers that
anon key with 404 instead.

With Service Key (admin/background operations, every visibility):

Use for background jobs, webhooks, cron, admin operations
Function receives payload only (no user context)
Database queries bypass RLS (admin access)

With Auth User Token (user-facing, authenticated or public functions):

Use for user-initiated actions
Includes users from anonymous sign-ins

Function receives payload + __volcano_auth context:

{
  user_id: "uuid",
  email: "user@example.com",
  project_id: "uuid",
  role: "authenticated" or "anonymous"
}

Database queries enforce RLS (user-scoped data)

With Anon Key (public functions only):

Requires anon key permission: functions.invoke
Function must have visibility: public
Function receives payload only (no __volcano_auth)

Reserved payload keys: the top-level __volcano_auth and
__volcano_http keys are reserved. Volcano removes caller-supplied
values for both before the function runs; only an auth user token adds
a server-built __volcano_auth, and only HTTP-mode ingress sets
__volcano_http: true.

Transport and CORS:

This operation is the authenticated direct RPC endpoint and always uses the
POST {payload: ...} contract, including for functions whose DNS ingress is
configured in HTTP mode.
The geo-routed DNS ingress is the function's invoke_url. It is on a
different domain from this API, so it cannot be derived from the API host.
RPC-mode DNS ingress accepts POST at /. HTTP-mode DNS ingress accepts GET,
HEAD, POST, PUT, PATCH, and DELETE at / and nested paths.
Direct and RPC-mode CORS preflight advertises POST, OPTIONS. HTTP-mode DNS
preflight advertises GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS.
http_auth_mode: none applies only to public HTTP-mode DNS ingress; this
direct operation always requires a Volcano credential.

Durable functions are not invocable here. A durable function's id
answers 404, whatever its visibility, because a synchronous call would
run it with no execution record, no idempotency and no concurrency
accounting. Start one with
POST /durable-functions/{functionId}/executions.
'

Request body changed
- Content changed
  - Modified media type: application/json
    - Schema changed
      - Properties changed
        
        Modified property: payload
        
        Description changed from 'Payload to send to the function.

If invoked with auth user token, Volcano automatically injects __volcano_auth context:

{
  ...yourPayload,
  __volcano_auth: {
    user_id: "uuid",
    email: "user@example.com",
    project_id: "uuid",
    role: "authenticated" | "anonymous"
  }
}

' to 'Payload to send to the function.

If invoked with auth user token, Volcano automatically injects __volcano_auth context:

{
  ...yourPayload,
  __volcano_auth: {
    user_id: "uuid",
    email: "user@example.com",
    project_id: "uuid",
    role: "authenticated" | "anonymous"
  }
}

The top-level __volcano_auth and __volcano_http keys are reserved;
Volcano removes caller-supplied values for both.
'

GET /projects

Responses changed
- Modified response: 200
  - Content changed
    - Modified media type: application/json
      - Schema changed
        
        Properties changed
        
        Modified property: data
        
        Items changed
        
        Properties changed
        
        Modified property: health
        Property 'AllOf' changed
        Modified schema: #/components/schemas/ProjectHealthSummary
        Properties changed
        Modified property: status
        Description changed from '' to 'empty means no functions, frontends, databases, storage, Volcano Auth users, or Sandbox resources are listed. needs_attention means an operation needs review without confirmed service impairment, or a serving frontend whose edge recovery gave up needs a redeploy. degraded means a resource is only partly available or is unavailable for an expected, temporary reason, such as a frontend whose edge synchronization did not complete or a database being restored; critical means use is blocked. A failed workflow or deployment record alone does not establish an outage. Findings remain available for empty projects.'
        
        New enum values: [empty needs_attention]

POST /projects

Responses changed
- Modified response: 201
  - Content changed
    - Modified media type: application/json
      - Schema changed
        
        Properties changed
        
        Modified property: health
        
        Property 'AllOf' changed
        
        Modified schema: #/components/schemas/ProjectHealthSummary
        
        Properties changed
        Modified property: status
        Description changed from '' to 'empty means no functions, frontends, databases, storage, Volcano Auth users, or Sandbox resources are listed. needs_attention means an operation needs review without confirmed service impairment, or a serving frontend whose edge recovery gave up needs a redeploy. degraded means a resource is only partly available or is unavailable for an expected, temporary reason, such as a frontend whose edge synchronization did not complete or a database being restored; critical means use is blocked. A failed workflow or deployment record alone does not establish an outage. Findings remain available for empty projects.'
        
        New enum values: [empty needs_attention]

GET /projects/{id}

Responses changed
- Modified response: 200
  - Content changed
    - Modified media type: application/json
      - Schema changed
        
        Properties changed
        
        Modified property: health
        
        Property 'AllOf' changed
        
        Modified schema: #/components/schemas/ProjectHealthSummary
        
        Properties changed
        Modified property: status
        Description changed from '' to 'empty means no functions, frontends, databases, storage, Volcano Auth users, or Sandbox resources are listed. needs_attention means an operation needs review without confirmed service impairment, or a serving frontend whose edge recovery gave up needs a redeploy. degraded means a resource is only partly available or is unavailable for an expected, temporary reason, such as a frontend whose edge synchronization did not complete or a database being restored; critical means use is blocked. A failed workflow or deployment record alone does not establish an outage. Findings remain available for empty projects.'
        
        New enum values: [empty needs_attention]

PATCH /projects/{id}

Responses changed
- Modified response: 200
  - Content changed
    - Modified media type: application/json
      - Schema changed
        
        Properties changed
        
        Modified property: health
        
        Property 'AllOf' changed
        
        Modified schema: #/components/schemas/ProjectHealthSummary
        
        Properties changed
        Modified property: status
        Description changed from '' to 'empty means no functions, frontends, databases, storage, Volcano Auth users, or Sandbox resources are listed. needs_attention means an operation needs review without confirmed service impairment, or a serving frontend whose edge recovery gave up needs a redeploy. degraded means a resource is only partly available or is unavailable for an expected, temporary reason, such as a frontend whose edge synchronization did not complete or a database being restored; critical means use is blocked. A failed workflow or deployment record alone does not establish an outage. Findings remain available for empty projects.'
        
        New enum values: [empty needs_attention]

POST /projects/{id}/frontends

Description changed from 'Creates and deploys a frontend for the project.
If a frontend with the same name already exists in the project, this operation updates that
frontend using the uploaded archive and starts a new deployment. A deployment that starts
immediately returns status: provisioning, then transitions to active, degraded, or
failed. If another deployment is running, the response preserves the frontend's current status
and exposes the queued deployment through pending_deployment_id.
Existing frontend traffic continues to use an available runtime while the new deployment builds
and provisions. Each deployment publishes its own static assets before the runtimes switch to its
build, and the live build's assets keep serving until the new deployment is live, so a page loaded
mid-deployment resolves its assets whichever build served it. A failed redeploy puts the runtimes
back on the build they were running, leaves the frontend active on the previous deployment, and
records the attempted deployment as failed. degraded means the runtime remains available but
edge synchronization requires recovery; Volcano retries the edge step without rebuilding. Only one deployment may run for a
given frontend, while independent frontends and projects can deploy concurrently.
For monorepos, provide app_root as a relative path from the uploaded archive root
to the Next.js app that should be built. Omit it for single-app archives.
Supported frontend environments are Next.js 15.x and 16.x with Node.js
22.x or 24.x. The Node.js runtime is inferred from
package.json engines.node; if omitted, Volcano uses Node.js 22.x.
The selected Node.js family must also satisfy the installed Next.js package's
engines.node constraint. Volcano tests Next 15.5.27 (^18.18.0 || ^19.8.0 || >=20.0.0) and Next 16.4.0 (>=20.9.0).
Source archive size is enforced by the API with SOURCE_ARCHIVE_SIZE_LIMIT_MB; the CLI
does not apply its own source archive size limit. After the final container images are
built, the publish build enforces LAMBDA_TARGET_CONTAINER_SIZE_LIMIT_MB before pushing.
This operation is limited by plan-based frontend deployment quotas (FREE_FRONTEND_DEPLOYMENTS, PRO_FRONTEND_DEPLOYMENTS).
Each project can contain up to 10,000 frontends regardless of plan.
' to 'Creates and deploys a frontend for the project.
If a frontend with the same name already exists in the project, this operation updates that
frontend using the uploaded archive and starts a new deployment. A deployment that starts
immediately returns status: provisioning, then transitions to active, degraded, or
failed. If another deployment is running, the response preserves the frontend's current status
and exposes the queued deployment through pending_deployment_id.
Existing frontend traffic continues to use an available runtime while the new deployment builds
and provisions. Each deployment publishes its own static assets before the runtimes switch to its
build, and the live build's assets keep serving until the new deployment is live, so a page loaded
mid-deployment resolves its assets whichever build served it. A failed redeploy puts the runtimes
back on the build they were running, leaves the frontend active on the previous deployment, and
records the attempted deployment as failed. degraded means the runtime remains available but
edge synchronization requires recovery; Volcano retries the edge step without rebuilding. Only one deployment may run for a
given frontend, while independent frontends and projects can deploy concurrently.
For monorepos, provide app_root as a relative path from the uploaded archive root
to the Next.js app that should be built. Omit it for single-app archives.
Supported frontend environments are Next.js 15.x and 16.x with Node.js
22.x or 24.x. The Node.js runtime is inferred from
package.json engines.node; if omitted, Volcano uses Node.js 22.x.
The selected Node.js family must also satisfy the installed Next.js package's
engines.node constraint. Volcano tests Next 15.5.28 (^18.18.0 || ^19.8.0 || >=20.0.0) and Next 16.4.1 (>=20.9.0).
Source archive size is enforced by the API with SOURCE_ARCHIVE_SIZE_LIMIT_MB; the CLI
does not apply its own source archive size limit. After the final container images are
built, the publish build enforces LAMBDA_TARGET_CONTAINER_SIZE_LIMIT_MB before pushing.
This operation is limited by plan-based frontend deployment quotas (FREE_FRONTEND_DEPLOYMENTS, PRO_FRONTEND_DEPLOYMENTS).
Each project can contain up to 10,000 frontends regardless of plan.
'

GET /projects/{id}/health

Description changed from 'Returns a fast control-plane health snapshot for the project and its
deployed resources. The endpoint does not run live provider probes.
A successful request returns 200 even when the project status is
unhealthy; transport and authorization failures use HTTP errors.
' to 'Returns a fast control-plane health snapshot for the project and its
deployed resources. The endpoint does not run live provider probes.
A successful request returns 200 even when the project status is
degraded or critical; transport and authorization failures use HTTP
errors.
'
Responses changed
- Modified response: 200
  - Content changed
    - Modified media type: application/json
      - Schema changed
        
        Properties changed
        
        Modified property: checks
        
        Items changed
        
        Properties changed
        
        Modified property: scope
        Properties changed
        Modified property: resource
        Properties changed
        Modified property: type
        New enum values: [database_branch]
        
        Modified property: status
        Description changed from '' to 'empty means no functions, frontends, databases, storage, Volcano Auth users, or Sandbox resources are listed. needs_attention means an operation needs review without confirmed service impairment, or a serving frontend whose edge recovery gave up needs a redeploy. degraded means a resource is only partly available or is unavailable for an expected, temporary reason, such as a frontend whose edge synchronization did not complete or a database being restored; critical means use is blocked. A failed workflow or deployment record alone does not establish an outage. Findings remain available for empty projects.'
        
        New enum values: [empty needs_attention]
        
        Modified property: findings
        
        Items changed
        
        Properties changed
        
        Modified property: scope
        Properties changed
        Modified property: resource
        Properties changed
        Modified property: type
        New enum values: [database_branch]
        
        Modified property: status
        Description changed from '' to 'empty means no functions, frontends, databases, storage, Volcano Auth users, or Sandbox resources are listed. needs_attention means an operation needs review without confirmed service impairment, or a serving frontend whose edge recovery gave up needs a redeploy. degraded means a resource is only partly available or is unavailable for an expected, temporary reason, such as a frontend whose edge synchronization did not complete or a database being restored; critical means use is blocked. A failed workflow or deployment record alone does not establish an outage. Findings remain available for empty projects.'
        
        New enum values: [empty needs_attention]
        
        Modified property: status
        
        Description changed from '' to 'empty means no functions, frontends, databases, storage, Volcano Auth users, or Sandbox resources are listed. needs_attention means an operation needs review without confirmed service impairment, or a serving frontend whose edge recovery gave up needs a redeploy. degraded means a resource is only partly available or is unavailable for an expected, temporary reason, such as a frontend whose edge synchronization did not complete or a database being restored; critical means use is blocked. A failed workflow or deployment record alone does not establish an outage. Findings remain available for empty projects.'
        
        New enum values: [empty needs_attention]

DELETE /projects/{id}/logo

Responses changed
- Modified response: 200
  - Content changed
    - Modified media type: application/json
      - Schema changed
        
        Properties changed
        
        Modified property: health
        
        Property 'AllOf' changed
        
        Modified schema: #/components/schemas/ProjectHealthSummary
        
        Properties changed
        Modified property: status
        Description changed from '' to 'empty means no functions, frontends, databases, storage, Volcano Auth users, or Sandbox resources are listed. needs_attention means an operation needs review without confirmed service impairment, or a serving frontend whose edge recovery gave up needs a redeploy. degraded means a resource is only partly available or is unavailable for an expected, temporary reason, such as a frontend whose edge synchronization did not complete or a database being restored; critical means use is blocked. A failed workflow or deployment record alone does not establish an outage. Findings remain available for empty projects.'
        
        New enum values: [empty needs_attention]

POST /projects/{id}/logo

Responses changed
- Modified response: 200
  - Content changed
    - Modified media type: application/json
      - Schema changed
        
        Properties changed
        
        Modified property: health
        
        Property 'AllOf' changed
        
        Modified schema: #/components/schemas/ProjectHealthSummary
        
        Properties changed
        Modified property: status
        Description changed from '' to 'empty means no functions, frontends, databases, storage, Volcano Auth users, or Sandbox resources are listed. needs_attention means an operation needs review without confirmed service impairment, or a serving frontend whose edge recovery gave up needs a redeploy. degraded means a resource is only partly available or is unavailable for an expected, temporary reason, such as a frontend whose edge synchronization did not complete or a database being restored; critical means use is blocked. A failed workflow or deployment record alone does not establish an outage. Findings remain available for empty projects.'
        
        New enum values: [empty needs_attention]

POST /projects/{id}/service-keys

Request body changed
- Content changed
  - Modified media type: application/json
    - Schema changed
      - Properties changed
        
        Modified property: permissions
        
        Description changed from 'Optional least-privilege scope for the key. When omitted, empty, or
        containing only blank strings, the key is granted full access ([""])
        for backward compatibility. Provide an explicit list (e.g.
        ["functions.invoke", "locks.manage"]) to restrict the key; ""
        grants everything. Scope enforcement applies to function invocation,
        storage object operations, and project locks.
        ' to 'Optional least-privilege scope for the key. When omitted, empty, or
        containing only blank strings, the key is granted full access ([""])
        for backward compatibility. Provide an explicit list (e.g.
        ["functions.invoke", "locks.manage"]) to restrict the key; ""
        grants everything. Scope enforcement applies to function invocation,
        storage object operations, project locks, and server-side auth proxy
        metadata (auth.signin, auth.signup, auth.refresh, auth.logout,
        auth.password_reset).
        '

DELETE /projects/{id}/storage/buckets/{bucketName}/policies/{policyId}

Responses changed
- New response: 404

Validation

Contract generation completed in the source workflow run.
Target repository CI validates the generated result.

CLAassistant · 2026-09-10T22:01:01Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

swkeever

[P2] Update the pinned contract SHA alongside this sync. Both required Ruby suites fail the bundled-contract assertion in spec/volcano_generation_spec.rb: expected d8d8f53d847bfdc31c6a9aa5d583a8541f67be3a52b79cd754163660d001a9a8, actual 90f23da23d78af8e2be84044333b891f5f58ed29638146c620cd9cb67fde4d9c. The new snapshot matches Hosting 111313e148bad1bbd3537a509b357e6d1abdaa0c/api/openapi.bundled.yaml. Update the fixture after validating that contract and rerun bundle exec rake quality. This failure also prevents the later injected-defect and package smoke checks from running.

CI evidence: https://github.com/Kong/volcano-sdk-ruby/actions/runs/38667886847/job/116203898115

tkkhq

The non-blocking checksum defect in the existing review remains: spec/volcano_generation_spec.rb:10,52 expects d8d8f53d847bfdc31c6a9aa5d583a8541f67be3a52b79cd754163660d001a9a8, while the vendored contract hashes to 90f23da23d78af8e2be84044333b891f5f58ed29638146c620cd9cb67fde4d9c. Update the expected digest and pass bundle exec rake quality before merge; the Ruby suites and Quality Gate still fail.

kong Bot force-pushed the chore/sync-openapi branch 6 times, most recently from c6391e8 to ea3d391 Compare September 5, 2026 02:49

kong Bot force-pushed the chore/sync-openapi branch 2 times, most recently from 1af2768 to 09b12fe Compare September 10, 2026 22:00

kong Bot force-pushed the chore/sync-openapi branch 13 times, most recently from 574efbb to 3d26a9c Compare September 17, 2026 18:05

kong Bot force-pushed the chore/sync-openapi branch 8 times, most recently from 4f5a9fd to 3fada80 Compare September 19, 2026 06:17

kong Bot force-pushed the chore/sync-openapi branch 14 times, most recently from aae2405 to 02ea9ac Compare September 30, 2026 01:43

kong Bot force-pushed the chore/sync-openapi branch 12 times, most recently from 8254557 to ba78d30 Compare October 7, 2026 19:00

swkeever reviewed Oct 15, 2026

View reviewed changes

tkkhq previously approved these changes Oct 15, 2026

View reviewed changes

marckong mentioned this pull request Oct 15, 2026

fix(sandboxes)!: drop the removed idle timeout and accept an unlimited session expiry #351

Open

chore(api): sync OpenAPI contract

2e34183

Navigation Menu

Repository navigation

chore(api): sync OpenAPI contract - #5

chore(api): sync OpenAPI contract#5
kong[bot] wants to merge 1 commit into
mainfrom
chore/sync-openapi

kong Bot commented Aug 30, 2026 •

edited

Loading

Uh oh!

CLAassistant commented Sep 10, 2026

Uh oh!

swkeever left a comment

Uh oh!

tkkhq left a comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

kong Bot commented Aug 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

API change report

Public API

New Endpoints: 3

Deleted Endpoints: None

Modified Endpoints: 20

Validation

Uh oh!

CLAassistant commented Sep 10, 2026

Uh oh!

swkeever left a comment

Choose a reason for hiding this comment

Uh oh!

tkkhq left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kong Bot commented Aug 30, 2026 •

edited

Loading