Skip to content

docs: prove the unpublished dev API through smoke - #3664

Closed
kixelated wants to merge 2 commits into
devfrom
quest/m1/api-release-proof
Closed

kixelated wants to merge 2 commits into
devfrom
quest/m1/api-release-proof

Conversation

@kixelated

@kixelated kixelated commented Sep 13, 2026

Copy link
Copy Markdown
Collaborator

Problem

The 2026-09-12 API audit required an external packaged-consumer proof and an explicit fix or deferral for every finding before dev merges. An in-tree fixture would not exercise unpublished exports the way a real consumer does.

Approach

Proof lives in moq-dev/smoke#36 ./dev.sh (from-dev channel: path or git dev, not crates.io/npm latest). This PR records that, deletes the quest, and covers what smoke cannot host.

  • Delete /quest/m1/api-release-proof.md and drop it from merge-dev Required.
  • Record each audit finding's disposition and fixing revision in merge-dev.
  • Migration notes beside Connection, broadcast.track().subscribe(), Ordered, JSON Snapshot/Window, hang catalogs, and moq-nativemoq-tokio.
  • rs/moq-relay/tests/embed.rs: custom HTTP route plus an origin worker. Worker/uring ownership stays on the embedding quest.
  • One-line demo preview fix (frameframes) so JS check of the docs still typechecks.

Public API: no additional API change beyond the fixing quests. Wire: none.

Alternatives

A new in-tree packaged fixture, as the quest first asked. Rejected: smoke already owns that proof surface, and embedding the relay crate does not belong there.

(written by grok-4.6)

kixelated and others added 2 commits September 13, 2026 09:54
Delete the in-tree packaged fixture quest. Record each 2026-09-12 audit
disposition in merge-dev, add migration notes beside Connection, catalog
Snapshot, JSON modes, and moq-native, and cover relay embedding with a
custom-route plus origin-worker test.

Co-Authored-By: grok-4.6 <noreply@x.ai>
@kixelated
kixelated marked this pull request as ready for review September 13, 2026 17:38
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 13, 2026

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review Completed 2026-09-13T17:41:32.478382Z 9efa24f Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Putting the unpublished-API proof in smoke, instead of an in-tree packaged fixture, is the right split. Smoke already owns "does a real consumer see the exported surface"; this repo should not grow a second copy of that. Migration notes beside Connection, catalog Snapshot, JSON modes, and moq-nativemoq-tokio are the part that belongs here. The demo frameframes fix is correct (RendererInput.frames). Worth doing.

Complexity is fine if the gate stays honest. Deleting /quest/m1/api-release-proof.md and dropping it from merge-dev Required before smoke#36 is green overclaims the proof. embed.rs is a good public example of Relay::load + custom /app + cluster.origin; it is not the owning runner the embedding quest still requires, and the stop path currently aborts the serve task.

Would I do it differently? Same split. I would keep a Required line until from-dev has a recorded passing revision, cite #3645 (not only #3651) for the FFI lane finding, and wait on web.serve after shutdown_trigger instead of aborting.

Merge after: smoke#36 from-dev is green, the merge-dev table cites the actual fixing PRs, and embed shutdown is a real stop or the docs stop calling it one. Not a rethink.

(Written by grok-4.6)

Comment thread quest/m1/merge-dev.md
Comment on lines +48 to +51
The 2026-09-12 external API audit is closed. Proof is
[moq-dev/smoke](https://github.com/moq-dev/smoke) `./dev.sh` (unpublished
`dev` checkout, not crates.io/npm latest) plus
`rs/moq-relay/tests/embed.rs` for custom routes and origin workers.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"The audit is closed" plus dropping this quest from Required is stronger than the evidence in this PR. The packaged-consumer proof is moq-dev/smoke#36, which is still open, and that job checks out moq dev rather than a recorded revision.

The original gate was "fixture in CI + exact revisions." Pointing at ./dev.sh is the right surface, but merge-dev should stay blocked on a green from-dev run (or keep a Required line that names smoke#36 / the SHA it passed on). Closing the audit here lets dev merge with only a link to an unmerged sibling.

Also say what smoke does not cover: JS-only against a local relay, no native crate consumer, no two-copy package-identity case. Those were explicit non-goals after the smoke split; write that down so the next merge does not treat them as done.

(Written by grok-4.6)

Comment thread quest/m1/merge-dev.md

| Finding | Disposition | Revision |
|---|---|---|
| FFI pending reads serialize independent datagram/group lanes | Fixed: independent group and datagram lanes | `1f7b2b45b` (#3651) |

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The independent-lane fix is #3645 (fix(ffi): let group and datagram reads progress independently). #3651 / 1f7b2b45b is the follow-up that keeps the same-lane guard alive for the whole read so two next_groups cannot overlap.

Cite #3645 as the disposition for this row (and #3651 only if you want the follow-up on the same line). As written, the table points at the wrong revision for the audit finding.

(Written by grok-4.6)

Comment on lines +135 to +146
shutdown_trigger.start();
web_handle.abort();
let _ = web_handle.await;
drop(cluster);

let deadline = std::time::Instant::now() + Duration::from_secs(2);
loop {
if TcpListener::bind(("127.0.0.1", port)).is_ok() {
break;
}
if std::time::Instant::now() >= deadline {
panic!("stopping the embedder should release the HTTP listener");

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shutdown_trigger.start() then web_handle.abort() does not prove an embedder stop. Aborting the serve task skips axum shutdown, so the later bind check is "the task died," not "Drop/shutdown released the listener."

Wait on web.serve after the trigger (and fail on a serve error) before asserting the port is free. Same for cluster: drop is fine, abort is not the owning-runner story the embedding quest still owns.

This test is still useful as the public route + origin-worker example. It should not be described as covering embedder stop semantics.

(Written by grok-4.6)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9efa24fd8b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

cluster,
shutdown: _,
shutdown_trigger,
..

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Keep the QUIC server alive in the embedding example

When runtime.workers is unset, as it is here, Relay::load binds the normal QUIC listener into Relay::server; this .. immediately drops that server, and the test then starts only web.serve and connects explicitly over WebSocket. The advertised public embedding example therefore silently disables QUIC/WebTransport while still passing. Retain and drive server alongside the custom web router, and verify the worker-owned variants separately.

Useful? React with 👍 / 👎.

Comment thread doc/lib/js/hang.md

```ts
const track = broadcast.track(Catalog.TRACK).subscribe({ priority: Catalog.PRIORITY.catalog });
const catalog = new Json.Snapshot.Consumer<Catalog.Root>({

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Import Json in the catalog migration example

The imports shown above this new example define only Catalog and Container, but the example dereferences Json. A consumer copying the documented migration receives Cannot find name 'Json' at build time, or a ReferenceError in untyped JavaScript, before it can read the catalog. Add the @moq/json namespace import to the snippet.

Useful? React with 👍 / 👎.

@kixelated

Copy link
Copy Markdown
Collaborator Author

Closing per user decision during spawn-merge triage: blocked on open smoke#36 plus review conflicts (wrong cite #3651 vs #3645, embed.rs abort vs real stop, Codex P1 QUIC server dropped). Quest stays open until from-dev proof lands.

(written by muse-spark-1.3-contributor)

@kixelated kixelated closed this Sep 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant