Catcrafts/Crafter.Debug
Watch
2
0
Fork
You've already forked Crafter.Debug
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: the QUIC transport, where Crafter.Network comes from, and limits

Browse source 
The agent notes describe the wire, list :Transport and :Quic, explain
how to build against a Network worktree with CRAFTER_DEBUG_NETWORK, and
how to test a listening session. They add the one thread Crafter.Debug
starts, the TLS and size limits, and gotchas: Crafter.Network must be
named alike by a consumer that uses it too, last 0, and replying before
raising a flag the main loop acts on. The README says the Session needs
a pool worker, that a project pinning its own Crafter.Network can't add
Crafter.Debug yet, and what ShouldServeOverQuic covers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Jorijn van der Graaf 2026-11-01 03:07:09 +01:00
commit 15e0b4954d
Signed by: jorijnvdgraaf
GPG key ID: 2937E59CDCC1BCFB
2 changed files with 24 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

8
README.md
View file

@ -68,11 +68,13 @@ extern "C" Configuration CrafterBuildProject(std::span<const std::string_view> a
A dependency that two paths in the build graph share must get the **same arg list on both**. Otherwise crafter-build refuses the graph with "module … built twice". Build one `depArgs` and give it to every dependency, as above.
That includes Crafter.Network, which Crafter.Debug takes from `https://forgejo.catcrafts.net/Catcrafts/Crafter.Network.git`, unpinned (with `--local`, from `../Crafter.Network`). If your project depends on Crafter.Network too, name it the same way. A project that pins its own Crafter.Network to a commit can't add Crafter.Debug yet.
**2. In `main`**, start a session and pump it once per frame. Gate the parts the agent should be able to pause:
```cpp
import MyApp.DebugShim; // see "Without #ifdefs" below
ThreadPool::Start(); // the session's transport runs on the pool
ThreadPool::Start(); // the session's transport needs a pool worker
#ifdef MYAPP_DEBUG_API
Debug::Session debug({ .name = "MyApp" });
MyApp::RegisterDebug(); // your commands and watches
@ -84,7 +86,7 @@ while (running && !Debug::QuitRequested()) {
}
```
The `Session` must be destroyed before `main` returns and before `ThreadPool::Stop()`, because msquic waits for open connections at exit. A stack object in `main`, as above, does that.
The `Session` must be destroyed before `main` returns and before `ThreadPool::Stop()`, because msquic waits for open connections at exit. A stack object in `main`, as above, does that. It needs the pool started with at least one worker (`Start(1)` starts none) and throws without one.
**3. Register what the agent needs** in debug-only source files, which `project.cpp` adds only under the flag. See "The app side" below.
@ -319,6 +321,8 @@ cd examples/Basic && crafter-build --debug-api -r
- **Library and core tests** run in-process, against a `Session` built with `listen = false` and a fake transport.
- **`ShouldRunClientCommands`** runs the real client against a real session that way.
- **`ShouldServeOverQuic`** runs a listening session and drives it over loopback with the client's own QUIC transport. It covers discovery, calls, `log --follow`, wrong tokens, oversized requests, parallel requests, and shutdown with a client connected.
- **Crafter.Network** comes from forgejo, or from `../Crafter.Network` with `--local`. To build against another checkout, a worktree say, set `CRAFTER_DEBUG_NETWORK` to its `project.cpp`.
- **`AGENTS.template.md`** has the conventions.
Licensed LGPL-3.0-only; the examples are MIT.