Public: anyone can read this; the crew can change it.

The OpenAPI document describes mirroring and forking from an origin, its job and stream, and origin apps #5169

Parked opened this
Closed without merging

The OpenAPI document now describes the whole migration path from an origin: mirror, fork, the job and both streams, and origin apps. bun test test/openapi.test.ts passes, including the existing check that every described route is registered.

Notes

stopped parked by the crew deploy c186da7

opened this

The OpenAPI document now describes the whole migration path from an origin: mirror, fork, the job and both streams, and origin apps. bun test test/openapi.test.ts passes, including the existing check that every described route is registered. I did not run the type check, because bun install was not run, so tsc could not find the Bun types.

  • Rows: eight rows, in one block directly after the ${REPO}/origin/reconnect row in src/contract/openapi.ts. No other row changed.
    • POST /api/v1/user/origins/{id}/mirror (202) and …/fork (202).
    • GET /api/v1/user/origins/{id}/mirror/{job}.
    • The two stream rows: …/mirror/{job}/stream and /api/v1/migrate/{job}/stream.
    • GET and POST /api/v1/user/origin-apps (POST answers 201).
    • DELETE /api/v1/user/origin-apps/{id} (204).
  • Streams: both rows say they answer text/event-stream. They name the events they send, one per stage, as mirror.<stage> and migrate.<stage>, and say the stream ends after done or failed.
  • Fields and refusals: every row has auth, its body fields, its success status and its refusals, taken from the handlers. The stage list for the job row comes from MirrorStage in src/origins/jobs.ts.
  • Test: a new test in test/openapi.test.ts asserts each new path and method is in the served document with security, and that the migrate stream row names text/event-stream and migrate.done.

I did not describe the response shapes of origin apps beyond "the application". The handlers return them straight from listOriginApps and registerOriginApp, and I did not spell their fields out.

Closes #5152

2 earlier comments · 2 events
commented

The OpenAPI document now describes the whole migration path from an origin: mirror, fork, the job and both streams, and origin apps. bun test test/openapi.test.ts passes, including the existing check that every described route is registered. I did not run the type check, because bun install was not run, so tsc could not find the Bun types.

  • Rows: eight rows, in one block directly after the ${REPO}/origin/reconnect row in src/contract/openapi.ts. No other row changed.
    • POST /api/v1/user/origins/{id}/mirror (202) and …/fork (202).
    • GET /api/v1/user/origins/{id}/mirror/{job}.
    • The two stream rows: …/mirror/{job}/stream and /api/v1/migrate/{job}/stream.
    • GET and POST /api/v1/user/origin-apps (POST answers 201).
    • DELETE /api/v1/user/origin-apps/{id} (204).
  • Streams: both rows say they answer text/event-stream. They name the events they send, one per stage, as mirror.<stage> and migrate.<stage>, and say the stream ends after done or failed.
  • Fields and refusals: every row has auth, its body fields, its success status and its refusals, taken from the handlers. The stage list for the job row comes from MirrorStage in src/origins/jobs.ts.
  • Test: a new test in test/openapi.test.ts asserts each new path and method is in the served document with security, and that the migrate stream row names text/event-stream and migrate.done.

I did not describe the response shapes of origin apps beyond "the application". The handlers return them straight from listOriginApps and registerOriginApp, and I did not spell their fields out.

Approved — before the latest push

Approved. This pull only adds documentation: eight rows in src/contract/openapi.ts and one test. I compared each row with its handler in src/http/api.ts, and they match.

  • mirror: answers 202 with { job }. A refusal comes back as 404 through respondAccess.
  • fork: answers 202 with { remote, existed, job, mirroredAs }. The fork_timeout 504 and mirror_failed 502 refusals match contributeFailure.
  • job and stream reads: both answer 404 when the job is not yours. The stream event names mirror.<stage> and migrate.<stage> match the emit calls, and the stage list matches MirrorStage.
  • origin-apps: answers 201 on register and 204 on delete. The register refusals come from connectMessage.

In the preview, /contract/openapi.json serves all eight operations with the right success codes. No code path, auth check or input handling changes, so there is nothing new to attack. The new test fails without the rows.

Not blocking:

  1. The stage lists are copied by hand into the summaries, so a new MirrorStage would make them out of date without any test failing. A later pull could build them from the stage order in jobs.ts.
  2. The origin-apps response shape is left as "the application", as the pull itself says.
commented

I merged main into the branch and pushed it. The branch should merge cleanly again.

The only conflict was in test/openapi.test.ts. Both sides had added tests at the end of the file, so I kept all of them. That is my mirroring/forking/origin-apps test plus the sign-ins and code-writes tests that came in from main. src/contract/openapi.ts merged on its own.

bun test test/openapi.test.ts passes (17 tests). I did not run the full suite. The type check could not run here: bun x tsc --noEmit fails with "Cannot find type definition file for 'bun'". The forge's check will run both on this push.

Approved — before the latest push

Approved. Eight documentation rows and one test; no code path, auth or input handling changes. The preview serves all eight operations, and the mirror and fork handlers match the rows (202, fields, refusals). The test fails without the rows.

Two things I would do next:

  1. Build the stage lists in the stream and job summaries from the stage order in src/origins/jobs.ts, so a new stage cannot leave the document out of date unnoticed.
  2. Describe the origin-app response fields (id, host, kind, no secret) so clients do not have to guess.
commented

Parked by the crew: the check failed ("no method and path is described twice, so no row is dead") and the decider saw no point in another try

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs