From a65b41ba9d065270d4d9172dc3db65074810ca3d Mon Sep 17 00:00:00 2001 From: Tomas Beran Date: Thu, 6 Aug 2026 15:22:27 +0200 Subject: [PATCH] docs: exclude internal-only envd endpoints from public API reference Six envd/orchestrator internals (/freeze, /unfreeze, /collapse, /fsfreeze, /fsthaw, /files/compose) leak in from the upstream envd spec. The SDKs never call them - they are internals of the pause/resume path. Their multi-sentence summaries also exceed the macOS 255-byte filename limit Mintlify derives from 'summary' (notably /fsfreeze), which aborts the whole API-reference build. Add them to excluded_exact in filter_paths() so a re-add upstream cannot re-leak them, and drop the six path blocks plus the now-orphaned CollapseResult and ComposeRequest schemas from openapi-public.yml (both must change together or the weekly regen re-adds them). --- openapi-public.yml | 269 -------------------------- scripts/generate_openapi_reference.py | 18 +- 2 files changed, 17 insertions(+), 270 deletions(-) diff --git a/openapi-public.yml b/openapi-public.yml index fd3d6aae..59a53318 100644 --- a/openapi-public.yml +++ b/openapi-public.yml @@ -1467,183 +1467,6 @@ paths: - Envd servers: - *id004 - /freeze: - post: - summary: Freeze user/pty cgroups before pause. Written directly by envd to avoid - Process.Start / shell overhead under load. - security: - - *id005 - responses: - '204': - description: Cgroups frozen - '500': - $ref: '#/components/responses/InternalServerError' - '503': - description: Freeze lock is held by another operation - '502': *id003 - parameters: - - name: E2b-Sandbox-Id - in: header - required: true - description: Identifier of the target sandbox. Routes the request to that - sandbox's envd over the shared sandbox host. - schema: - type: string - - name: E2b-Sandbox-Port - in: header - required: true - description: Port envd listens on inside the sandbox (default 49983). - schema: - type: integer - default: 49983 - operationId: postFreeze - tags: - - Envd - servers: - - *id004 - /unfreeze: - post: - summary: Unfreeze user/pty cgroups. Intended ONLY for the orchestrator's pause-failure - rollback path; the normal resume thaw happens via /init's deferred unfreeze, - not here. - security: - - *id005 - responses: - '204': - description: Cgroups unfrozen - '500': - $ref: '#/components/responses/InternalServerError' - '503': - description: Freeze lock is held by another operation - '502': *id003 - parameters: - - name: E2b-Sandbox-Id - in: header - required: true - description: Identifier of the target sandbox. Routes the request to that - sandbox's envd over the shared sandbox host. - schema: - type: string - - name: E2b-Sandbox-Port - in: header - required: true - description: Port envd listens on inside the sandbox (default 49983). - schema: - type: integer - default: 49983 - operationId: postUnfreeze - tags: - - Envd - servers: - - *id004 - /collapse: - post: - summary: Collapse envd's own anonymous heap into 2 MiB transparent hugepages - before pause, so on resume envd touches fewer distinct guest-physical frames - (each a cold fault). Best-effort. - security: - - *id005 - responses: - '200': - description: Heap collapsed - content: - application/json: - schema: - $ref: '#/components/schemas/CollapseResult' - '500': - $ref: '#/components/responses/InternalServerError' - '502': *id003 - parameters: - - name: E2b-Sandbox-Id - in: header - required: true - description: Identifier of the target sandbox. Routes the request to that - sandbox's envd over the shared sandbox host. - schema: - type: string - - name: E2b-Sandbox-Port - in: header - required: true - description: Port envd listens on inside the sandbox (default 49983). - schema: - type: integer - default: 49983 - operationId: postCollapse - tags: - - Envd - servers: - - *id004 - /fsfreeze: - post: - summary: Freeze the guest rootfs (FIFREEZE) before a filesystem-only pause so - it is flushed to a consistent on-disk state, closing the sync->pause race. - Idempotent. On a successful filesystem-only pause the VM is rebooted, so no - thaw is needed; the orchestrator thaws only on the pause-failure path. - security: - - *id005 - responses: - '204': - description: Rootfs frozen - '500': - $ref: '#/components/responses/InternalServerError' - '503': - description: Freeze lock is held by another operation - '502': *id003 - parameters: - - name: E2b-Sandbox-Id - in: header - required: true - description: Identifier of the target sandbox. Routes the request to that - sandbox's envd over the shared sandbox host. - schema: - type: string - - name: E2b-Sandbox-Port - in: header - required: true - description: Port envd listens on inside the sandbox (default 49983). - schema: - type: integer - default: 49983 - operationId: postFsfreeze - tags: - - Envd - servers: - - *id004 - /fsthaw: - post: - summary: Thaw the guest rootfs (FITHAW). Intended ONLY for the orchestrator's - pause-failure rollback path, so a frozen filesystem cannot leave the live - VM deadlocked. Idempotent. - security: - - *id005 - responses: - '204': - description: Rootfs thawed - '500': - $ref: '#/components/responses/InternalServerError' - '503': - description: Freeze lock is held by another operation - '502': *id003 - parameters: - - name: E2b-Sandbox-Id - in: header - required: true - description: Identifier of the target sandbox. Routes the request to that - sandbox's envd over the shared sandbox host. - schema: - type: string - - name: E2b-Sandbox-Port - in: header - required: true - description: Port envd listens on inside the sandbox (default 49983). - schema: - type: integer - default: 49983 - operationId: postFsthaw - tags: - - Envd - servers: - - *id004 /envs: get: summary: Environment variables @@ -1882,56 +1705,6 @@ paths: operationId: uploadFile servers: - *id004 - /files/compose: - post: - summary: Compose multiple files into a single file using zero-copy concatenation. - Source files are deleted after successful composition. - tags: - - Filesystem - security: - - *id005 - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/ComposeRequest' - responses: - '200': - description: Files composed successfully - content: - application/json: - schema: - $ref: '#/components/schemas/EntryInfo' - '400': - $ref: '#/components/responses/InvalidPath' - '401': - $ref: '#/components/responses/InvalidUser' - '404': - $ref: '#/components/responses/FileNotFound' - '500': - $ref: '#/components/responses/InternalServerError' - '507': - $ref: '#/components/responses/NotEnoughDiskSpace' - '502': *id003 - parameters: - - name: E2b-Sandbox-Id - in: header - required: true - description: Identifier of the target sandbox. Routes the request to that - sandbox's envd over the shared sandbox host. - schema: - type: string - - name: E2b-Sandbox-Port - in: header - required: true - description: Port envd listens on inside the sandbox (default 49983). - schema: - type: integer - default: 49983 - operationId: postFilesCompose - servers: - - *id004 /filesystem.Filesystem/CreateWatcher: post: tags: @@ -3225,48 +2998,6 @@ components: type: integer description: Total disk space in bytes format: int64 - CollapseResult: - type: object - description: Per-call statistics from a heap collapse - properties: - regions: - type: integer - description: Anonymous read-write regions scanned - chunks: - type: integer - description: 2 MiB chunks attempted - collapsed: - type: integer - description: Chunks whose base pages were actually migrated into a new hugepage - (real work) - alreadyHuge: - type: integer - description: Chunks MADV_COLLAPSE accepted but were already hugepages (no - work) - skipped: - type: integer - description: Chunks that could not be collapsed (empty or ineligible) - elapsedMs: - type: integer - format: int64 - description: Wall-clock time spent collapsing, in milliseconds - ComposeRequest: - type: object - required: - - source_paths - - destination - properties: - source_paths: - type: array - items: - type: string - description: Ordered list of source file paths to concatenate - destination: - type: string - description: Destination file path for the composed file - username: - type: string - description: User for setting ownership and resolving relative paths connect-protocol-version: type: number title: Connect-Protocol-Version diff --git a/scripts/generate_openapi_reference.py b/scripts/generate_openapi_reference.py index ccb96a4c..8a13eb5b 100755 --- a/scripts/generate_openapi_reference.py +++ b/scripts/generate_openapi_reference.py @@ -1389,7 +1389,23 @@ def filter_paths(spec: dict[str, Any]) -> None: """ # Remove explicitly excluded paths excluded_prefixes = ("/access-tokens", "/api-keys") - excluded_exact = {"/init"} + # Internal-only envd endpoints that leak in from the upstream spec. The SDKs + # never call these - they are envd/orchestrator internals for the pause and + # resume path (cgroup + filesystem freeze/thaw, heap collapse, zero-copy file + # compose). They must not appear in the developer-facing docs, and their + # multi-sentence summaries also blow past the macOS 255-byte filename limit + # Mintlify derives from `summary` (e.g. /fsfreeze), which aborts the whole + # API-reference build. Exclude them here so a re-add upstream cannot re-leak + # them into openapi-public.yml. + excluded_exact = { + "/init", + "/freeze", + "/unfreeze", + "/collapse", + "/fsfreeze", + "/fsthaw", + "/files/compose", + } to_remove = [ p for p in spec["paths"] if p.startswith(excluded_prefixes) or p in excluded_exact