Skip to content

cloud-artifact-api.mdx

Latest commit

 

History

History
126 lines (94 loc) · 3.58 KB

cloud-artifact-api.mdx

File metadata and controls

126 lines (94 loc) · 3.58 KB
Raw
title Cloud Environment Artifact API
description HTTP contract for publishing and resolving ObjectStack environment artifacts.

Cloud Environment Artifact API

The Cloud Environment Artifact API is the control-plane contract used to publish compiled metadata and activate immutable environment revisions. The framework runtime consumes the resulting artifact plus deployment config to boot the target environment.

The artifact envelope is defined by EnvironmentArtifactSchema in packages/spec/src/system/environment-artifact.zod.ts.

Publish endpoint

POST /api/v1/cloud/environments/:environment/metadata

The body is the compiled JSON produced by os compile or objectstack compile. The control plane validates the object payload, stores it as a new revision, computes a checksum, and returns the commit metadata used by runtime caches.

{
  "success": true,
  "data": {
    "environmentId": "env_prod",
    "commitId": "9ce1bd48dd7022b8",
    "checksum": { "algorithm": "sha256", "value": "..." }
  }
}

The CLI command is:

OS_CLOUD_URL=https://cloud.example.com \
OS_ENVIRONMENT_ID=env_prod \
os publish

Activate revision endpoint

POST /api/v1/cloud/environments/:environment/revisions/:commit/activate

Activating a revision changes the environment's current artifact pointer. Runtime nodes can then reload or refresh their environment kernel based on the new commit/checksum.

OS_CLOUD_URL=https://cloud.example.com \
OS_ENVIRONMENT_ID=env_prod \
os rollback --commit 9ce1bd48dd7022b8

Artifact envelope

EnvironmentArtifactSchema contains the immutable, cacheable portion of a deployment:

  • schemaVersion
  • environmentId
  • commitId
  • checksum
  • metadata
  • functions
  • manifest
  • optional builtAt, builtWith, and payloadRef

Deployment config does not belong in the artifact. Database coordinates, secrets, runtime credentials, and hostname bindings are mutable operational inputs provided by the host or Cloud control plane.

Runtime resolution

Environment-aware runtime hosts resolve the target environment before serving a data-plane request:

  1. /api/v1/environments/:environmentId/...
  2. Hostname through the environment registry
  3. X-Environment-Id
  4. session.activeEnvironmentId
  5. Configured default environment
  6. Single unambiguous environment

This resolution order is implemented by the cloud host distribution's kernel-resolver (@objectstack/objectos-runtime). The open-source dispatcher (packages/runtime/src/http-dispatcher.ts) only provides the seam: when no resolver is injected it serves every request from a single default kernel.

Control-plane routes under /api/v1/cloud/environments/... are management calls, not data-plane calls.

Reference implementation

File Purpose
packages/cli/src/commands/publish.ts CLI publish command and endpoint construction.
packages/cli/src/commands/rollback.ts CLI revision activation command.
packages/runtime/src/http-dispatcher.ts Kernel-resolution seam for per-request environment resolution. The concrete id/hostname registry ships in the host distribution @objectstack/objectos-runtime (not part of this open-source repo).
packages/cloud-connection/src/runtime-config-plugin.ts Console runtime-config for active/default environment state.
packages/spec/src/system/environment-artifact.zod.ts Normative artifact envelope schema.

Related