Doc system test

Question protocol

The init and validate HTTP calls between the CLI and a template, through the coordinator proxy - routes, ports, JSON, errors and timeouts.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/coordinator
  • durian.cloud/cyanprint/authoring
  • durian.cloud/cyanprint/registry
type
surface
related
issues
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+prompt-client-ignores-http-status
  • https://github.com/AtomiCloud/sulfone.boron/issues?q=TBD+init-proxy-no-timeout
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+validate-error-body-accepted

The problem. The template script runs in a container on the coordinator's Docker network; the CLI runs on a laptop. The two need a request/response contract that carries a whole question loop without the server keeping anything.

The idea. Two POST routes per template, both stateless: init (here are all answers and values so far, what next?) and validate (replay to your next question and judge this text). The CLI reaches them through the coordinator, which forwards each body unchanged to the template's shared container.

The sequence below is one question of web:5, from the CLI to the container and back.

sequenceDiagram
  participant CLI as CLI (cyanprompt)
  participant CO as coordinator :9000
  participant T as cyan-template-e5d07b3a… :5550
  CLI->>CO: POST /proxy/template/e5d07b3a-…/api/template/init
  CO->>T: POST /api/template/init (same body)
  T-->>CO: 200 questionnaire: question port + deterministicState
  CO-->>CLI: same status, same body
  Note over CLI: prompt shown, user types 3000
  CLI->>CO: POST /proxy/template/e5d07b3a-…/api/template/validate
  CO->>T: POST /api/template/validate (30 s limit)
  T-->>CO: 200 valid: null
  CO-->>CLI: 200 valid: null
  CLI->>CO: POST …/api/template/init (port added)
One question through the proxy

Routes and ports

The table is every route of the protocol. The coordinator path takes the template's version id with dashes.

HopMethod and pathTargetTime limit
CLI → coordinatorPOST <coordinator>/proxy/template/<version id>/api/template/initport 900030 s (CLI client default)
coordinator → templatePOST /api/template/initcyan-template-<version id, no dashes>:5550none
CLI → coordinatorPOST <coordinator>/proxy/template/<version id>/api/template/validateport 900030 s (CLI client default)
coordinator → templatePOST /api/template/validatecyan-template-<version id, no dashes>:555030 s
  • The default coordinator is http://coord.cyanprint.dev:9000 (--coordinator-endpoint, env CYANPRINT_COORDINATOR).
  • The container name has no session id: one shared container per template version serves every user and every session (container name).
  • Every SDK also answers GET / with {"Status":"OK","Message":"OK"} (capital keys); the protocol does not use it.
  • The CLI starts the question loop while the coordinator is still bootstrapping the session's processors (template run).

Init call

The request carries the answer map in wire spelling and the deterministic state under the plural name. Here is web:5's third init call in step 1 of the shop example:

jsonjson
{
"answers": {
"node_version": { "type": "string", "answer": "22" },
"module_type": { "type": "string", "answer": "esm" },
"name": { "type": "string", "answer": "shop" },
"port": { "type": "string", "answer": "3000" }
},
"deterministicStates": { "instance-id": "4f9c2e71-aaaa" }
}

A missing answer is a 200 question reply, with the state under the singular name:

jsonjson
{
"type": "questionnaire",
"deterministicState": { "instance-id": "4f9c2e71-aaaa" },
"question": { "type": "checkbox", "id": "features", "message": "Features?",
"desc": null, "options": ["docker", "storybook"] }
}

When every question is answered, a 200 final reply with the Cyan and no state:

jsonjson
{
"type": "final",
"cyan": {
"processors": [ { "name": "atomi/shop-render:1", "config": { "name": "shop", "port": "3000", "instanceId": "4f9c2e71-aaaa" },
"files": [ { "root": null, "glob": "**/*", "exclude": [], "type": "template" } ] } ],
"plugins": [ { "name": "atomi/shop-format:1", "config": {} } ]
}
}

Validate call

The request adds the candidate as a plain string. It has no question id: the answer map decides where the replay stops.

jsonjson
{
"answers": {
"node_version": { "type": "string", "answer": "22" },
"module_type": { "type": "string", "answer": "esm" },
"name": { "type": "string", "answer": "shop" }
},
"deterministicStates": { "instance-id": "4f9c2e71-aaaa" },
"validate": "80"
}

The reply is always 200 with valid set to null (accepted) or a reason (refused). An empty reason counts as accepted in all three SDKs.

jsonjson
{ "valid": "Use a port from 1024 to 65535" }

If the replay reaches the end instead of a question (the map already answers everything), the SDK throws "Not supposed to reach here for validation!".

Field spellings across SDKs

The CLI's spellings are fixed by its serde models. All three SDKs accept and return them:

FieldNodePython.NET
request statedeterministicStatesdeterministic_states, alias camelCaseDeterministicStates, camelCase JSON
reply statedeterministicStatedeterministic_state, alias camelCaseDeterministicState, camelCase JSON
answer type pickfrom the valuefrom the valuefrom the type tag
bad bodyno schema check400 {"error": "..."}framework binding error

Errors

  1. Coordinator could not read the body: 400 ProblemDetails (title, status, detail, type, trace_id, data; boron's JSON tag is trace_id, bo/model.go:17).
  2. Template unreachable, or its body unreadable: 502 ProblemDetails, title Upstream failed.
  3. Template answered: its status and body are passed through unchanged.
  4. On the CLI side, the prompt client never checks the status. It decodes the body as the reply it expects, and the two calls differ:
    • Init: the reply is a tagged union, so type must be questionnaire or final. A ProblemDetails (its type is a URL), a Python {"error": …} or an HTML error page fails to decode, and the loop ends with Err holding the decode error, not the server's message.
    • Validate: the reply is { "valid": string or null } and unknown keys are ignored. A ProblemDetails or a Python {"error": …} body has no valid key, so it decodes as valid: null, which means accepted. Only a body that is not JSON, or a dead connection, is an error (bug below).
  5. The CLI wraps that Err as 🚨 Template Prompting Error (status 400, type local) (prompt outcome). There is no retry.

Here is the real code for both ends of the proxy and the CLI client.

sulfone.iridiumcyancoordinator/src/template/executor.rs
  1. lines 190-214The template endpoint is the coordinator proxy path with the version id; a default reqwest blocking client is used (30 s limit).
    cyancoordinator/src/template/executor.rs:190-214rust
    // Setup Template Engine
    let template_endpoint = format!("{coord_endpoint}/proxy/template/{template_id}");
    let answers_clone = answers.cloned();
    let states_clone = deterministic_states.cloned();
    let self_clone = self.clone();
    let h22 = runtime.spawn_blocking(move || {
    if headless {
    // Headless mode prints nothing to stdout here — the single JSON
    // envelope is the only contract output; progress goes to stderr.
    eprintln!("🤖 Running headless template Q&A...");
    } else if answers_clone.is_some() {
    println!("🤖 Using provided answers...");
    } else {
    println!("🤖 Starting interactive template Q&A...");
    }
    let c22 = Rc::new(Client::new());
    let prompter = self_clone.new_template_engine(template_endpoint.as_str(), c22.clone());
    let state = if headless {
    // Headless re-derives deterministic state internally; the caller
    // supplies only answers.
    prompter.start_headless(answers_clone)
    } else {
    prompter.start_with(answers_clone, states_clone)
    };
  2. sulfone.iridium/cyanprompt/src/http/client.rs:24-48init and validate: POST JSON, then decode the body; the HTTP status is never checked.
    cyanprompt/src/http/client.rs:24-48rust
    pub fn prompt_template(
    &self,
    r: &TemplateAnswerReq,
    ) -> Result<TemplateRes, Box<dyn Error + Send>> {
    let host = (self.endpoint).to_string().to_owned();
    let endpoint = host + "/api/template/init".to_string().as_str();
    self.json_post(endpoint, r)
    .map_err(|x| Box::new(x) as Box<dyn Error + Send>)
    .and_then(|resp| {
    resp.json()
    .map_err(|e| Box::new(e) as Box<dyn Error + Send>)
    })
    }
    pub fn validate_template(
    &self,
    r: &TemplateValidateReq,
    ) -> Result<TemplateValidRes, Box<dyn Error + 'static + Send + Sync>> {
    let host = (self.endpoint).to_string().to_owned();
    let endpoint = host + "/api/template/validate".to_string().as_str();
    self.json_post(endpoint, r)
    .map_err(|x| x.into())
    .and_then(|resp| resp.json().map_err(|e| e.into()))
    }
  3. sulfone.boron/server.go:596-607init route: container name from the version id with no session, port 5550.
    server.go:596-607rust
    r.POST("/proxy/template/:cyanId/api/template/init", func(c *gin.Context) {
    cyanId := c.Param("cyanId")
    fmt.Println("📇 Cyan ID:", cyanId)
    d := docker_executor.DockerContainerReference{
    CyanId: cyanId,
    CyanType: "template",
    SessionId: "",
    }
    endpoint := "http://" + docker_executor.DockerContainerToString(d) + ":5550/api/template/init"
    fmt.Println("🌐 Upstream Endpoint:", endpoint)
  4. sulfone.boron/server.go:624-638init forward: the whole body is printed to the log, then sent with http.Post (no time limit); failure is 502.
    server.go:624-638rust
    fmt.Println("📦 Request Body:", string(reqBody))
    resp, err := http.Post(endpoint, c.GetHeader("Content-Type"), bytes.NewBuffer(reqBody))
    if err != nil {
    // Handle error
    c.JSON(http.StatusBadGateway, ProblemDetails{
    Title: "Upstream failed",
    Status: 502,
    Detail: "Failed to forward request to upstream template",
    Type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502",
    TraceId: nil,
    Data: []string{err.Error()},
    })
    return
    }
  5. sulfone.boron/server.go:690-694validate forward: only the body size is logged; a client with a 30 s limit.
    server.go:690-694rust
    fmt.Println("📦 Request Body Size:", len(reqBody), "bytes")
    // Forward the request body directly without reading it first
    client := &http.Client{Timeout: 30 * time.Second}
    resp, err := client.Post(endpoint, c.GetHeader("Content-Type"), bytes.NewBuffer(reqBody))
  6. sulfone.boron/server.go:724-725The template's status and body are passed back as they are.
    server.go:724-725rust
    }
    c.Data(resp.StatusCode, resp.Header.Get("Content-Type"), body)
  7. sulfone.helium/sdks/node/src/main.ts:116-131Node SDK: both routes log the request body and reply 200.
    sdks/node/src/main.ts:116-131rust
    app.post('/api/template/init', async (req: Request, res: Response) => {
    console.log(req.body);
    const result = await templateService.template(TemplateInputMapper.answerToDomain(req.body));
    res.json(TemplateOutputMapper.ToResp(result));
    res.end();
    });
    app.post('/api/template/validate', async (req: Request, res: Response) => {
    console.log(req.body);
    const result = await templateService.validate(TemplateInputMapper.validateToDomain(req.body));
    const r = {
    valid: result,
    } satisfies TemplateValidRes;
    res.json(r);
    res.end();
    });

Why it is built this way

Hard cases

  • A slow script fails at 30 s. The CLI's client gives up after 30 s on any one call. A template that does slow work (a network call, a large file read) before its first question fails every init call, and each replay repeats that work.
  • The status is ignored. A 500 whose body happens to decode as a reply is taken as one; a 200 with a bad body is an error. For validate, any status with a JSON object body that lacks valid counts as "accepted".
  • A thrown error in the script. Node: the async handler has no catch and Express 4 does not catch a rejected handler, so the handler sends no reply. Python and .NET: an unhandled exception becomes the framework's error reply, which the CLI cannot decode. Found while reading; not run.
  • One container for everyone. Two users' loops on web:5 hit the same container; each request builds its own inquirer and map, so they do not mix, but anything the author keeps in module-level variables is shared.

Questions for the designer

  1. What set the 30 s limits, and should the init forward have one too?
  2. Should the prompt client check the HTTP status and show the template's error text?
  3. Is an OpenAPI file for this contract kept anywhere, as the design note says? No static file is in the clones. The .NET SDK serves a generated one (StartTemplate calls AddSwaggerGen, UseSwagger and UseSwaggerUI, Server.cs:115-125, with SwaggerSubType on the answer tags, AnswerReq.cs:9-13); the Node and Python SDKs have none. Is the .NET output the contract?
  4. Should a validate call that returns a non-200 status or a body without valid be refused instead of accepted?