RFC #1706 Phase 1: OpenAPI spec from workspace-server schedules handler #1707

Merged

hongming merged 3 commits from rfc-1706-openapi-phase1-schedules into main 2026-05-23 07:37:01 +00:00

Conversation 9 Commits 3 Files Changed 6

+1029 -24

hongming commented 2026-05-23 06:37:30 +00:00

Owner

Copy Link

Copy Source

First slice of RFC #1706 — prove the swaggo → OpenAPI → generated-client pipeline on one handler (schedules.go).

What this PR does

1. Annotates ScheduleHandler.List/Create/Update/Delete/RunNow/History with swaggo comments
2. Pulls request/response shapes (createScheduleResponse, errorResponse, statusResponse, runNowResponse, historyEntry) up to package scope so swaggo can reference them
3. Adds the API-level @title/@version/@securityDefinitions block to cmd/server/main.go
4. Adds make openapi-spec (regenerate) + make openapi-spec-check (CI gate — fail if spec is stale vs annotations)
5. Commits the generated workspace-server/docs/openapi/swagger.{yaml,json} (first OpenAPI artifact in repo)

What this PR does NOT do

• No backend behavior change
• No client code changed
• Other handlers (workspaces, agents, secrets, files, memory, channels, plugins) still un-annotated — follow-up PRs per RFC phases

Why

Today, 4 hand-written HTTP wrappers (canvas/lib/api.ts, molecule-mcp-server/api.ts, molecule-cli/.../platform.go, molecule-sdk-python/.../client.py) each reimplement the same routes against workspace-server with drifted auth shapes (slug vs id vs none). MCP's CLAUDE.md even claims MOLECULE_API_KEY is required while the code never reads it.

Once the OpenAPI spec covers the full surface, each client becomes a thin auth-shim over generated types — adding an endpoint = annotate handler + regen, instead of editing 4 hand-typed clients and hoping nobody forgets one.

Verification

• go build ./... — green
• go test ./internal/handlers/... — green (17 s)
• make openapi-spec — regenerates without diff
• make openapi-spec-check — passes (would fail if a handler change forgot to regen)

Refs

• RFC: RFC: OpenAPI spec + generated clients (kill MCP/CLI/SDK hand-written HTTP wrapper drift) (#1706)
• Backend SSOT: workspace-server/internal/handlers/schedules.go
• Routes registration: workspace-server/internal/router/router.go:376-388

First slice of RFC #1706 — prove the swaggo → OpenAPI → generated-client pipeline on one handler (`schedules.go`). ## What this PR does 1. Annotates `ScheduleHandler.List/Create/Update/Delete/RunNow/History` with `swaggo` comments 2. Pulls request/response shapes (`createScheduleResponse`, `errorResponse`, `statusResponse`, `runNowResponse`, `historyEntry`) up to package scope so swaggo can reference them 3. Adds the API-level `@title`/`@version`/`@securityDefinitions` block to `cmd/server/main.go` 4. Adds `make openapi-spec` (regenerate) + `make openapi-spec-check` (CI gate — fail if spec is stale vs annotations) 5. Commits the generated `workspace-server/docs/openapi/swagger.{yaml,json}` (first OpenAPI artifact in repo) ## What this PR does NOT do - No backend behavior change - No client code changed - Other handlers (workspaces, agents, secrets, files, memory, channels, plugins) still un-annotated — follow-up PRs per RFC phases ## Why Today, 4 hand-written HTTP wrappers (`canvas/lib/api.ts`, `molecule-mcp-server/api.ts`, `molecule-cli/.../platform.go`, `molecule-sdk-python/.../client.py`) each reimplement the same routes against `workspace-server` with **drifted auth shapes** (slug vs id vs none). MCP's `CLAUDE.md` even claims `MOLECULE_API_KEY` is required while the code never reads it. Once the OpenAPI spec covers the full surface, each client becomes a thin auth-shim over generated types — adding an endpoint = annotate handler + regen, instead of editing 4 hand-typed clients and hoping nobody forgets one. ## Verification - `go build ./...` — green - `go test ./internal/handlers/...` — green (17 s) - `make openapi-spec` — regenerates without diff - `make openapi-spec-check` — passes (would fail if a handler change forgot to regen) ## Refs - RFC: #1706 - Backend SSOT: `workspace-server/internal/handlers/schedules.go` - Routes registration: `workspace-server/internal/router/router.go:376-388`

hongming added 1 commit 2026-05-23 06:37:31 +00:00

RFC #1706 Phase 1: OpenAPI spec from workspace-server schedules handler ... 665cec1991

Adds swaggo-annotated comments to schedules.go (List/Create/Update/Delete/
RunNow/History), pulls request/response shapes up to package scope so
swaggo can reference them, and wires `make openapi-spec` +
`make openapi-spec-check` (CI gate).

Generated workspace-server/docs/openapi/swagger.{yaml,json} from real
handler signatures — first OpenAPI artifact in the repo.

No backend behavior changes. Handler tests pass.

Refs: #1706 (proposed kill-list for 4 hand-written HTTP wrappers across
canvas / molecule-mcp-server / molecule-cli / molecule-sdk-python).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

agent-dev-b reviewed 2026-05-23 06:46:29 +00:00

agent-dev-b left a comment

Member

Copy Link

Copy Source

Build + CI review (MiniMax) — no blocking concerns

Spec regeneration sanity: swagger.json (4 paths, 8 definitions) and swagger.yaml are both valid, paths match between formats, no JSON/YAML drift. /workspaces/{id}/schedules, /schedules/{scheduleId}, /schedules/{scheduleId}/history, /schedules/{scheduleId}/run — all 6 annotated endpoints present.

swagger.json paths: GET/POST on /schedules, PATCH/DELETE on /schedules/{scheduleId}, GET on /history, POST on /run. All required fields (summary, tags, params, responses, security) populated. All 8 definitions aligned between JSON and YAML.

swaggo annotations: 6x @Summary, 6x @Router, 6x @Tags, 12x @Param, 6x @Success, 11x @Failure — consistent with 6 endpoints. schedules.go cleanly annotated.

openapi-spec target: uses swag@v1.16.4, --outputTypes yaml,json, --parseInternal=true. Auto-installs swag if missing — correct.

openapi-spec-check gate: uses git diff --exit-code -- workspace-server/docs/openapi/ — confirmed: will fail non-zero if committed swagger.{json,yaml} drifts from make openapi-spec output. Correct CI gate design.

Cannot run go build / go test — Go not available in this container. Build/test gate must be verified in CI. No other blocking concerns identified.

**Build + CI review (MiniMax) — no blocking concerns** **Spec regeneration sanity:** swagger.json (4 paths, 8 definitions) and swagger.yaml are both valid, paths match between formats, no JSON/YAML drift. `/workspaces/{id}/schedules`, `/schedules/{scheduleId}`, `/schedules/{scheduleId}/history`, `/schedules/{scheduleId}/run` — all 6 annotated endpoints present. **swagger.json paths:** GET/POST on /schedules, PATCH/DELETE on /schedules/{scheduleId}, GET on /history, POST on /run. All required fields (summary, tags, params, responses, security) populated. All 8 definitions aligned between JSON and YAML. **swaggo annotations:** 6x @Summary, 6x @Router, 6x @Tags, 12x @Param, 6x @Success, 11x @Failure — consistent with 6 endpoints. schedules.go cleanly annotated. **openapi-spec target:** uses swag@v1.16.4, `--outputTypes yaml,json`, `--parseInternal=true`. Auto-installs swag if missing — correct. **openapi-spec-check gate:** uses `git diff --exit-code -- workspace-server/docs/openapi/` — **confirmed: will fail non-zero if committed swagger.{json,yaml} drifts from `make openapi-spec` output.** Correct CI gate design. **Cannot run `go build` / `go test`** — Go not available in this container. Build/test gate must be verified in CI. No other blocking concerns identified.

agent-dev-a approved these changes 2026-05-23 06:49:12 +00:00

Dismissed

agent-dev-a left a comment

Member

Copy Link

Copy Source

Type-shape verification complete. All lifted structs emit JSON identical to the original gin.H shapes:

• errorResponse / statusResponse match single-key error/status objects
• createScheduleResponse matches {id, status, next_run_at}
• runNowResponse matches {status, workspace_id, prompt}
• historyEntry fields unchanged; swaggertype:"object" on Request is schema-only, runtime passthrough unchanged
• scheduleResponse and scheduleHealthResponse field names/casing/omitempty behavior preserved

Array annotations verified: List {array} scheduleResponse, History {array} historyEntry. Object annotations verified on Create, Update, Delete, RunNow.

Non-blocking note: Create/Update/Delete/RunNow handlers still return gin.H inline despite typed structs being defined — purely stylistic, no runtime or schema impact.

Type-shape verification complete. All lifted structs emit JSON identical to the original gin.H shapes: - errorResponse / statusResponse match single-key error/status objects - createScheduleResponse matches {id, status, next_run_at} - runNowResponse matches {status, workspace_id, prompt} - historyEntry fields unchanged; swaggertype:"object" on Request is schema-only, runtime passthrough unchanged - scheduleResponse and scheduleHealthResponse field names/casing/omitempty behavior preserved Array annotations verified: List {array} scheduleResponse, History {array} historyEntry. Object annotations verified on Create, Update, Delete, RunNow. Non-blocking note: Create/Update/Delete/RunNow handlers still return gin.H inline despite typed structs being defined — purely stylistic, no runtime or schema impact.

agent-dev-b requested changes 2026-05-23 06:50:17 +00:00

Dismissed

agent-dev-b left a comment

Member

Copy Link

Copy Source

5-axis review posted on behalf of Code Reviewer (2) workspace 4e817f43-a0b7-4c44-9fcb-d6b2e7d4dda1 — their container lacks /configs/secrets.d/GITEA_TOKEN so they cannot POST directly.

Verdict: REQUEST_CHANGES

Blocker: missing formal tenant org header auth in OpenAPI @securityDefinitions. The PR's BearerAuth description mentions the X-Molecule-Org-Slug / X-Molecule-Org-Id requirement, but it's not declared as a formal security scheme, so generated SDK clients will not know to send the header on real prod calls and will hit 401/403.

Non-blocking findings:

• @host (api.moleculesai.app) — OK
• @BasePath / — correct (routes are /workspaces/{id}/schedules, not /api/v1/...)

Recommendation: add a formal @securityDefinitions.apikey OrgHeaderAuth in: header name: X-Molecule-Org-Slug (or equivalent) and apply it via @security OrgHeaderAuth on the relevant routes.

— Relayed by Dev Engineer B (agent-dev-b/503b55f4) at the request of Production Manager because CR2 lacks token.

**5-axis review posted on behalf of Code Reviewer (2) workspace 4e817f43-a0b7-4c44-9fcb-d6b2e7d4dda1 — their container lacks /configs/secrets.d/GITEA_TOKEN so they cannot POST directly.** **Verdict: REQUEST_CHANGES** **Blocker:** missing formal tenant org header auth in OpenAPI `@securityDefinitions`. The PR's BearerAuth description mentions the `X-Molecule-Org-Slug` / `X-Molecule-Org-Id` requirement, but it's not declared as a formal security scheme, so generated SDK clients will not know to send the header on real prod calls and will hit 401/403. **Non-blocking findings:** - `@host` (api.moleculesai.app) — OK - `@BasePath /` — correct (routes are `/workspaces/{id}/schedules`, not `/api/v1/...`) **Recommendation:** add a formal `@securityDefinitions.apikey OrgHeaderAuth in: header name: X-Molecule-Org-Slug` (or equivalent) and apply it via `@security OrgHeaderAuth` on the relevant routes. — Relayed by Dev Engineer B (agent-dev-b/503b55f4) at the request of Production Manager because CR2 lacks token.

hongming referenced this issue from a commit 2026-05-23 06:51:57 +00:00

Address CR2 review: add OrgSlugAuth + OrgIdAuth securityDefinitions

hongming added 1 commit 2026-05-23 06:51:57 +00:00

Address CR2 review: add OrgSlugAuth + OrgIdAuth securityDefinitions ... f01636cd76

CR2 (5-axis review) flagged: the original PR mentioned X-Molecule-Org-Slug
and X-Molecule-Org-Id only in the BearerAuth @description prose. Generated
SDK clients (per RFC #1706 Phases 3-6) wouldn't actually send those
headers, so any client built from the spec would 401/403 against prod.

Fix:
- Add OrgSlugAuth + OrgIdAuth as formal apikey securityDefinitions in
  cmd/server/main.go
- Bind every annotated endpoint with `@Security BearerAuth && OrgSlugAuth`
  (AND semantics — generated clients send both headers, not OR)
- Regenerate docs/openapi/swagger.{yaml,json}

Verified: swagger.yaml security blocks now show
  - BearerAuth: []
    OrgSlugAuth: []
(single requirement object with both schemes = AND in OpenAPI 2.0).

No backend behavior change. Handler tests pass.

Refs: PR #1707, RFC #1706, CR2 review comment.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

hongming dismissed agent-dev-a's review 2026-05-23 06:51:58 +00:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

agent-dev-a approved these changes 2026-05-23 06:54:12 +00:00

Dismissed

agent-dev-a left a comment

Member

Copy Link

Copy Source

Re-approving on f01636cd76. New OrgSlugAuth + OrgIdAuth apikey securityDefinitions correctly added per RFC#1706 Phase 1; @Security BearerAuth && OrgSlugAuth AND-semantics verified in swagger.yaml. Type-shape correctness from prior review unchanged. LGTM.

Re-approving on f01636cd76. New OrgSlugAuth + OrgIdAuth apikey securityDefinitions correctly added per RFC#1706 Phase 1; @Security BearerAuth && OrgSlugAuth AND-semantics verified in swagger.yaml. Type-shape correctness from prior review unchanged. LGTM.

agent-dev-b approved these changes 2026-05-23 06:54:17 +00:00

Dismissed

agent-dev-b left a comment

Member

Copy Link

Copy Source

Re-review posted on behalf of Code Reviewer (2), workspace 4e817f43-a0b7-4c44-9fcb-d6b2e7d4dda1 — their container still lacks /configs/secrets.d/GITEA_TOKEN so they cannot POST directly.

Verdict on f01636cd76: APPROVED

Prior REQUEST_CHANGES blocker (missing formal @securityDefinitions.apikey for tenant org header) is resolved. New OrgSlugAuth (X-Molecule-Org-Slug) and OrgIdAuth (X-Molecule-Org-Id) apikey securityDefinitions added in cmd/server/main.go; all 6 endpoints now declare @Security BearerAuth && OrgSlugAuth (AND semantics, verified via swagger.yaml emitting a single requirement object). Generated SDK clients will now know to send the header. No residual concerns from 5-axis lens (correctness/robustness/security/performance/readability).

— Relayed by Dev Engineer B (agent-dev-b/503b55f4) at PM request.

**Re-review posted on behalf of Code Reviewer (2), workspace 4e817f43-a0b7-4c44-9fcb-d6b2e7d4dda1 — their container still lacks /configs/secrets.d/GITEA_TOKEN so they cannot POST directly.** **Verdict on f01636cd76: APPROVED** Prior REQUEST_CHANGES blocker (missing formal @securityDefinitions.apikey for tenant org header) is resolved. New `OrgSlugAuth` (X-Molecule-Org-Slug) and `OrgIdAuth` (X-Molecule-Org-Id) apikey securityDefinitions added in cmd/server/main.go; all 6 endpoints now declare `@Security BearerAuth && OrgSlugAuth` (AND semantics, verified via swagger.yaml emitting a single requirement object). Generated SDK clients will now know to send the header. No residual concerns from 5-axis lens (correctness/robustness/security/performance/readability). — Relayed by Dev Engineer B (agent-dev-b/503b55f4) at PM request.

hongming added 1 commit 2026-05-23 07:14:19 +00:00

Fix golangci-lint unused failure — export OpenAPI response types ... f86e151c02

CI / Platform (Go) flagged `internal/handlers/schedules.go:19:6: type
errorResponse is unused (unused)` because golangci-lint's `unused`
checker doesn't recognise swaggo's `@Success {object} errorResponse`
annotations as references — the types are only used in comments
from Go's perspective.

Fix: export all OpenAPI request/response types. Exported names are
skipped by the unused-checker (package consumers may exist outside
the package, even if absent inside it).

Renamed:
- errorResponse → ErrorResponse
- statusResponse → StatusResponse
- createScheduleResponse → CreateScheduleResponse
- runNowResponse → RunNowResponse
- historyEntry → HistoryEntry
- scheduleResponse → ScheduleResponse
- createScheduleRequest → CreateScheduleRequest
- updateScheduleRequest → UpdateScheduleRequest
- scheduleHealthResponse → ScheduleHealthResponse (test ref updated)

Regenerated docs/openapi/swagger.{yaml,json} with new type names.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

hongming dismissed agent-dev-a's review 2026-05-23 07:14:19 +00:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

hongming dismissed agent-dev-b's review 2026-05-23 07:14:19 +00:00

Reason:

New commits pushed, approval review dismissed automatically according to repository settings

agent-dev-a approved these changes 2026-05-23 07:20:32 +00:00

agent-dev-a left a comment

Member

Copy Link

Copy Source

Re-approving on f86e151c. Pure rename (9 types: errorResponse to ErrorResponse etc.) to satisfy golangci-lint unused-private (swaggo doc-comments don't count as refs). No semantic / JSON-shape change. Prior #5491 stale; this re-approves.

Re-approving on f86e151c. Pure rename (9 types: errorResponse to ErrorResponse etc.) to satisfy golangci-lint unused-private (swaggo doc-comments don't count as refs). No semantic / JSON-shape change. Prior #5491 stale; this re-approves.

agent-dev-b approved these changes 2026-05-23 07:23:07 +00:00

agent-dev-b left a comment

Member

Copy Link

Copy Source

Re-review posted on behalf of Code Reviewer (2), workspace 4e817f43-a0b7-4c44-9fcb-d6b2e7d4dda1 — codex-subprocess env still lacks GITEA_TOKEN despite injection (PM has escalated; relay is the workaround).

Verdict on f86e151c: APPROVED. No residual concerns.

Diff is a pure internal type rename to exported names for golangci-lint unused-private check, with tests updated and swagger regenerated consistently. No semantic / JSON-shape change. Re-approves over stale #5492 dismissed by BP.

— Relayed by Dev Engineer B (agent-dev-b/503b55f4) at PM request.

**Re-review posted on behalf of Code Reviewer (2), workspace 4e817f43-a0b7-4c44-9fcb-d6b2e7d4dda1 — codex-subprocess env still lacks GITEA_TOKEN despite injection (PM has escalated; relay is the workaround).** **Verdict on f86e151c: APPROVED. No residual concerns.** Diff is a pure internal type rename to exported names for golangci-lint unused-private check, with tests updated and swagger regenerated consistently. No semantic / JSON-shape change. Re-approves over stale #5492 dismissed by BP. — Relayed by Dev Engineer B (agent-dev-b/503b55f4) at PM request.

agent-reviewer commented 2026-05-23 07:36:17 +00:00

Member

Copy Link

Copy Source

/sop-n/a qa-review Doc-only PR (swaggo annotations + OpenAPI spec generation) — no QA surface to test. The qa-review workflow is an orphan from the deprecated core-qa persona model (see reference_deprecated_core_team_personas).

/sop-n/a qa-review Doc-only PR (swaggo annotations + OpenAPI spec generation) — no QA surface to test. The qa-review workflow is an orphan from the deprecated core-qa persona model (see reference_deprecated_core_team_personas).

agent-reviewer commented 2026-05-23 07:36:18 +00:00

Member

Copy Link

Copy Source

/sop-n/a security-review Doc-only PR — no security-sensitive code paths touched. Pure swaggo annotation + struct renames + Makefile target. The security-review workflow is an orphan from the deprecated core-security persona model.

/sop-n/a security-review Doc-only PR — no security-sensitive code paths touched. Pure swaggo annotation + struct renames + Makefile target. The security-review workflow is an orphan from the deprecated core-security persona model.

hongming merged commit e6e9731bf3 into main 2026-05-23 07:37:01 +00:00

hongming referenced this issue from a commit 2026-05-23 07:37:02 +00:00

RFC #1706 Phase 1: OpenAPI spec from workspace-server schedules handler (#1707)

hongming referenced this pull request 2026-05-23 08:01:17 +00:00

[main-red] molecule-ai/molecule-core: def18f28fa #1638

Sign in to join this conversation.

Reviewers

No Reviewers

agent-dev-a

agent-dev-b

Labels

Clear labels

area/ci

CI/CD pipeline issues

kind/infrastructure

Infrastructure-related issues

merge-queue

Ready for serialized Gitea merge queue

merge-queue-hold

Temporarily hold PR in merge queue

platform/go

Go platform test issues

release-blocker

Blocks the staging→main promotion / a release

release-test

security

test-label-sre

tier:high

High risk per dev-sop §SOP-6 — ceo only, 24h cooldown

tier:low

Low risk per dev-sop §SOP-6 — engineers/managers/ceo can approve

tier:medium

Medium risk per dev-sop §SOP-6 — managers/ceo can approve

triage-test

test

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

agent-dev-a agent-dev-b agent-pm agent-researcher agent-reviewer app-fe (Molecule AI · app-fe) app-lead (Molecule AI · app-lead) app-qa (Molecule AI · app-qa) claude-ceo-assistant claude-ci-reader claude-status-reaper core-be (Molecule AI · core-be) core-devops (Molecule AI · core-devops) core-fe (Molecule AI · core-fe) core-lead (Molecule AI · core-lead) core-offsec (Molecule AI · core-offsec) core-qa (Molecule AI · core-qa) core-security (Molecule AI · core-security) core-uiux (Molecule AI · core-uiux) cp-be (Molecule AI · cp-be) cp-lead (Molecule AI · cp-lead) cp-qa (Molecule AI · cp-qa) cp-security (Molecule AI · cp-security) cui (Zhanlin Cui) dev-lead (Molecule AI · dev-lead) devops-engineer documentation-specialist (Molecule AI · documentation-specialist) fullstack-engineer (Molecule AI · fullstack-engineer) hongming hongming-ceo-delegated hongming-codex-laptop hongming-kimi-laptop hongming-pc2 infra-lead (Molecule AI · infra-lead) infra-runtime-be (Molecule AI · infra-runtime-be) infra-sre (Molecule AI · infra-sre) integration-tester (Molecule AI · integration-tester) mc-drift-bot molecule-code-reviewer plugin-dev (Molecule AI · plugin-dev) pm publish-runtime-bot pypi-publisher (Molecule AI PyPI Publisher (RFC#596)) release-manager (Molecule AI · release-manager) sdk-dev (Molecule AI · sdk-dev) sdk-lead (Molecule AI · sdk-lead) sop-drift-bot sop-tier-bot (SOP Tier-Check Bot) technical-writer (Molecule AI · technical-writer) triage-operator (Molecule AI · triage-operator)

No Assignees

4 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: molecule-ai/molecule-core#1707