/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Chat

Keywords on this page
WordMeaningExample
ConversationOne chat, owned by one account, with its messages inside it“Why is room 2 hot?”, 6 messages
ExchangeOne question and its answer, stored togethera user message and an assistant message
HistoryThe latest messages sent to agent as contextthe last 10
SSEServer-Sent Events: one HTTP answer that keeps sending small text framesdata: {"type":"token","text":"The "}
FrameOne SSE event, ended by a blank linea token frame
TokenA small piece of the answer, sent as soon as it exists"The "
CitationA part of a document that the answer is based on{"source":"floor-plans.qd", …}
ObjectIdMongoDB’s own id type. It never leaves the storage adaptershown as "6650c1…"
OwnerThe account in the sub of the claims3f2b
PortA Rust trait the core logic talks to, so tests can swap the real thing for a fakeConversationStore, AgentClient
AdapterThe real code behind a port: it talks to MongoDB, to agent, or to HTTPMongoConversations
StreamA value that gives out its items one at a time, as they become readythe answer, token by token

chat is a Rust service (Axum, MongoDB) in backend/chat. It does four things:

  1. Stores conversations. Each one belongs to one account.
  2. Sends each question to agent, together with the recent history.
  3. Relays the answer to the browser as it is written, token by token.
  4. Saves the exchange once the answer is whole.

agent stores nothing: every /ask stands alone. chat is the part that remembers.

Role in the system: Chat. The other side of the stream: Agent.


The idea in one minute

Think of a receptionist who takes written questions for an expert in the next room.

flowchart LR
    B["browser"] -- "POST question" --> C[("chat<br/>the receptionist")]
    C -- "POST /ask + history" --> A["agent<br/>the expert"]
    A -- "tokens, then done" --> C
    C -- "tokens (SSE)" --> B
    C --- DB[("MongoDB<br/>the folders")]

The files

Ports and adapters. tests/architecture_fitness.rs fails the build when a rule breaks.

PathWhat it holdsMay not import
src/domain/conversation.rsConversation, ChatMessage, Citation, the limits, validate_text, the history window, the automatic titleaxum, mongodb, reqwest, bson, crate::service, crate::adapters
src/domain/identity.rsGatewayClaims {user_id, raw}same
src/service/conversations.rsThe use cases, and the streaming Exchangeany framework, crate::adapters
src/service/ports.rsConversationStore, AgentClient, AgentEvent
src/adapters/driving/http_api/The claims extractor, the handlers, the SSE frames, the error mappingcrate::adapters::driven
src/adapters/driven/persistence/The MongoDB store. The only file that knows ObjectId
src/adapters/driven/agent.rsAgentService: calls agent /ask and reads its SSE stream
src/adapters/ratelimit.rs300 requests per minute per client IP

“Driving” means the outside world drives the service (HTTP comes in). “Driven” means the service drives the outside world (it calls MongoDB and agent).

Other rules the tests enforce:

flowchart LR
    H["http_api<br/>controllers"] --> S["Conversations"]
    S --> D["domain<br/>rules"]
    S -. "ConversationStore" .-> M["MongoConversations"]
    S -. "AgentClient" .-> A["AgentService"]
    M --> DB[("chatdb.conversations")]
    A -- "POST /ask, x-gateway-claims" --> Ag["agent"]

domain/conversation.rs: the rules, with no framework

The limits

pub const MAX_MESSAGES: usize = 100;
pub const MAX_MESSAGE_LENGTH: usize = 8000;
pub const MAX_TITLE_LENGTH: usize = 120;
pub const DEFAULT_TITLE: &str = "New chat";

A conversation holds at most 100 messages. A question is at most 8000 characters, a title at most 120. A conversation made without a title is called New chat.

The shapes

pub struct Citation {
    pub chunk_id: String,
    pub document_id: String,
    pub source: String,
    #[serde(default)]
    pub section_path: Option<String>,
}

A citation keeps the Python names of agent (chunk_id, not chunkId). It is stored and returned unchanged, so a blanket rename to camelCase would silently break every citation. A missing section_path is written as null.

pub struct ChatMessage {
    #[serde(rename = "_id")]
    pub id: String,
    pub role: Role,
    pub content: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub citations: Option<Vec<Citation>>,
    #[serde(rename = "createdAt")]
    pub created_at: String,
}

One message. role is user or assistant. skip_serializing_if means a message with no citations has no citations key at all. The id and the date are plain strings: the domain never sees ObjectId or MongoDB dates.

pub struct Conversation {
    pub id: String,
    pub user_id: String,
    pub title: String,
    pub messages: Vec<ChatMessage>,
    pub created_at: String,
    pub updated_at: String,
}

The full folder. ConversationSummary is the same without messages, used for the list.

Checking a text

pub fn validate_text(
    value: Option<&str>,
    name: &str,
    max_length: usize,
) -> Result<String, DomainError> {
    let text = value
        .map(str::trim)
        .filter(|t| !t.is_empty())
        .ok_or_else(|| DomainError::Validation(format!("{name} must be a non-empty string")))?;

    if text.chars().count() > max_length {
        return Err(DomainError::Validation(format!(
            "{name} cannot exceed {max_length} characters"
        )));
    }
    Ok(text.to_string())
}
  1. Trim the spaces. Missing, or empty after trimming: "{name} must be a non-empty string".
  2. Count the characters (not bytes) of the trimmed text. Too long: "{name} cannot exceed {max} characters".
  3. Return the trimmed text.

Trimming first matters: trailing spaces never push a valid question over the limit.

Example. " Why is room 2 hot? " becomes "Why is room 2 hot?", 18 characters, fine.

Three small rules on a conversation

impl Conversation {
    pub fn has_room_for_exchange(&self) -> bool {
        self.messages.len() + 2 <= MAX_MESSAGES
    }

    pub fn recent_history(&self, limit: usize) -> Vec<HistoryTurn> {
        self.messages
            .iter()
            .skip(self.messages.len().saturating_sub(limit))
            .map(|m| HistoryTurn { role: m.role, content: m.content.clone() })
            .collect()
    }

    pub fn title_from_first_question(&self, question: &str) -> Option<String> {
        if self.title != DEFAULT_TITLE || !self.messages.is_empty() {
            return None;
        }
        Some(question.chars().take(MAX_TITLE_LENGTH).collect())
    }
}

The title field has three states

pub enum TitleField<'a> {
    Absent,
    Present(Option<&'a str>),
}

A body without title is not the same as a body with "title": null. The first means “use the default”. The second is an error.

BodyResult
{}Title New chat
{"title":"Floor 3"}Title Floor 3, trimmed
{"title":null} or {"title":" "}400 title must be a non-empty string

A typed Option<String> field cannot tell “absent” from “null” (both become None), so the handler keeps the body as raw JSON and decides itself.


service/ports.rs: the two doors

#[async_trait]
pub trait ConversationStore: Send + Sync {
    async fn create(&self, user_id: &str, title: &str) -> anyhow::Result<Conversation>;
    async fn summaries(&self, user_id: &str) -> anyhow::Result<Vec<ConversationSummary>>;
    async fn find_owned(&self, user_id: &str, id: &str) -> anyhow::Result<Option<Conversation>>;
    async fn rename(&self, user_id: &str, id: &str, title: &str) -> anyhow::Result<Option<Conversation>>;
    async fn delete_owned(&self, user_id: &str, id: &str) -> anyhow::Result<bool>;
    async fn append_exchange(
        &self, user_id: &str, id: &str,
        user_message: NewMessage, assistant_message: NewMessage,
        new_title: Option<&str>,
    ) -> anyhow::Result<Option<ChatMessage>>;
}

Everything the service may ask the storage. Look at the names: find_owned, delete_owned. Every method takes the user_id. There is no “find by id alone”, so forgetting the ownership check is not possible. Option means “not found” and is not an error.

pub enum AgentEvent {
    Token(String),
    Done {
        answer: Option<String>,
        citations: Vec<Citation>,
    },
}

pub type AnswerStream = Pin<Box<dyn Stream<Item = anyhow::Result<AgentEvent>> + Send>>;

#[async_trait]
pub trait AgentClient: Send + Sync {
    async fn ask(&self, question: &str, history: &[HistoryTurn], claims_header: &str)
        -> Result<AnswerStream, DomainError>;
}

What agent can say: a Token, or Done. answer is an Option because an older agent may not send it. ask resolves as soon as agent has accepted the question and the headers are in. Every later token arrives on the stream. So “could not reach agent” and "agent said 500” are errors of ask, before anything is streamed.


service/conversations.rs: the use cases

The simple ones just add the owner check and the validation:

pub async fn open(&self, user_id: &str, id: &str) -> Result<Conversation, DomainError> {
    self.store
        .find_owned(user_id, id)
        .await?
        .ok_or_else(DomainError::not_found)
}

A miss is NotFound. rename validates the title first, then calls the store. delete turns “deleted nothing” into NotFound. create picks the default title or validates the given one.

send_message: before the first token

pub async fn send_message(
    &self,
    user_id: &str,
    conversation_id: &str,
    content: Option<&str>,
    claims_header: &str,
) -> Result<impl Stream<Item = Result<ChatEvent, DomainError>> + Send + use<>, DomainError>
{
    let question = validate_text(content, "content", MAX_MESSAGE_LENGTH)?;
    let conversation = self.open(user_id, conversation_id).await?;

    if !conversation.has_room_for_exchange() {
        return Err(DomainError::Conflict("Conversation message limit reached".to_string()));
    }

    let history = conversation.recent_history(self.history_limit);
    let upstream = self.agent.ask(&question, &history, claims_header).await?;
    // … build and return the stream

The order is on purpose, cheapest check first:

  1. Validate the text. A bad request costs no database read.
  2. Load the owned conversation. Not found (or someone else’s): NotFound.
  3. Check the room. Full: Conflict (409), and agent is never called.
  4. Build the history and ask agent, forwarding the caller’s own claims header.

Every failure up to here is the outer Err, so the HTTP layer can still answer with a normal status code. The answer has not started.

The return type says it: Result<Stream<…>, DomainError>. The outer Result is “before the first token”. The items inside the stream are “after”.

The stream: Exchange

struct Exchange {
    upstream: AnswerStream,
    answer: Answer,
    finished: bool,
}

struct Answer {
    store: Arc<dyn ConversationStore>,
    user_id: String,
    conversation_id: String,
    question: String,
    new_title: Option<String>,
    text: String,
}

The state of one answer in progress: the stream from agent, the text so far (text), and what is needed to save at the end. They are two structs because the upstream stream is Send but not Sync, so nothing borrowed across an await can live inside it.

async fn step(mut self) -> Option<(Result<ChatEvent, DomainError>, Self)> {
    if self.finished {
        return None;
    }

    match self.upstream.next().await {
        Some(Ok(AgentEvent::Token(text))) => {
            self.answer.text.push_str(&text);
            Some((Ok(ChatEvent::Token(text)), self))
        }
        Some(Ok(AgentEvent::Done { answer, citations })) => {
            self.finished = true;
            if let Some(answer) = answer {
                self.answer.text = answer;
            }
            let persisted = self.answer.persist(citations).await.map(ChatEvent::Done);
            Some((persisted, self))
        }
        Some(Err(_)) => {
            self.finished = true;
            Some((Err(DomainError::BadGateway("agent stream ended unexpectedly".to_string())), self))
        }
        None => {
            self.finished = true;
            Some((Err(DomainError::BadGateway("agent returned an invalid response".to_string())), self))
        }
    }
}

futures::stream::unfold calls step again and again. Each call waits for the next event from agent and produces one event for the browser:

agent giveschat does
Token(text)Add the text to the answer kept in memory. Pass the token on
Done {answer, citations}Stop. If answer is there, it replaces the joined tokens. Save the exchange. Pass on the stored message
An unreadable frame, or a broken connectionStop with agent stream ended unexpectedly
The stream ends with no DoneStop with agent returned an invalid response

Why does answer win? agent can rewrite what the model wrote: it removes citation marks it cannot back, or text streamed before a tool call. The tokens the browser saw may have those; the stored answer should not. An agent that sends no answer gets the joined tokens stored.

The last row is the key one. Done is the only signal that the answer is whole. Without it there is nothing safe to save.

Saving

async fn persist(&self, citations: Vec<Citation>) -> Result<ChatMessage, DomainError> {
    self.store
        .append_exchange(
            &self.user_id,
            &self.conversation_id,
            NewMessage { role: Role::User, content: self.question.clone(), citations: None },
            NewMessage { role: Role::Assistant, content: self.text.clone(), citations: Some(citations) },
            self.new_title.as_deref(),
        )
        .await?
        .ok_or_else(DomainError::not_found)
}

Both halves, plus the new title if there is one, go in one store call. Nothing is written before this. If the conversation was deleted meanwhile, the store returns None and the browser gets a Conversation not found error frame.


adapters/driven/agent.rs: talking to agent

The request

const CONNECT_TIMEOUT: Duration = Duration::from_secs(5);
const READ_TIMEOUT: Duration = Duration::from_secs(60);

client: reqwest::Client::builder()
    .connect_timeout(CONNECT_TIMEOUT)
    .read_timeout(READ_TIMEOUT)
    .build()

Two timeouts, and no total timeout. A total timeout would kill a long answer in the middle. The connect timeout (5 s) bounds the handshake. The read timeout (60 s) applies to each wait for the next bytes, not to the whole response, so it still ends a stream that goes silent but lets a slow, steady answer run for minutes.

let response = self
    .client
    .post(format!("{}/ask", self.base_url))
    .header(CLAIMS_HEADER, claims_header)
    .json(&AskRequest { question, history, stream: true })
    .send()
    .await
    .map_err(|_| DomainError::BadGateway("Could not reach agent".to_string()))?;

if !response.status().is_success() {
    return Err(DomainError::BadGateway(format!("agent returned {}", response.status().as_u16())));
}

Ok(Box::pin(frames(response.bytes_stream())))

Send {"question", "history", "stream": true} with the caller’s own x-gateway-claims, so agent checks rights as that user. Can’t connect: Could not reach agent. Not a 2xx: agent returned 503 (or whatever). Otherwise hand the raw byte stream to frames.

Turning bytes into events

Bytes arrive in pieces that do not line up with frames. One frame can come in two reads, and one read can hold three frames. This part of the file solves that.

fn take_frames(buffer: &mut Vec<u8>) -> Vec<Vec<u8>> {
    let mut frames = Vec::new();
    while let Some(end) = buffer
        .windows(2)
        .position(|w| w == b"\n\n")
        .map(|start| start + 2)
    {
        frames.push(buffer.drain(..end).collect());
    }
    frames
}

An SSE frame ends with a blank line (\n\n). Look for it in the buffer. Each time one is found, cut everything up to and including it as a whole frame (drain). Whatever is left stays in the buffer, waiting for more bytes. The buffer is bytes, not text, until the cut: a character like ° takes 2 bytes, and cutting text in the middle of it would break it.

fn parse_frame(raw: &[u8]) -> Option<anyhow::Result<AgentEvent>> {
    let text = String::from_utf8_lossy(raw);
    let payload: String = text
        .lines()
        .filter_map(|line| line.strip_prefix("data:"))
        .map(|value| value.strip_prefix(' ').unwrap_or(value))
        .collect::<Vec<_>>()
        .join("\n");

    if payload.trim().is_empty() {
        return None;
    }

    match serde_json::from_str::<AgentFrame>(&payload) {
        Ok(AgentFrame::Token { text }) => Some(Ok(AgentEvent::Token(text))),
        Ok(AgentFrame::Done { answer, citations }) => Some(Ok(AgentEvent::Done { answer, citations })),
        Ok(AgentFrame::Ignored) => None,
        Err(e) => Some(Err(anyhow::anyhow!("unreadable agent frame: {e}"))),
    }
}

Read one whole frame:

  1. Keep only the lines that start with data:, drop the optional space after the colon, join them with newlines. A comment line like : ping has no data:, so it vanishes.
  2. Nothing left: skip (None).
  3. Read the JSON by its type.
#[derive(Deserialize)]
#[serde(tag = "type", rename_all = "lowercase")]
enum AgentFrame {
    Token { #[serde(default)] text: String },
    Done { #[serde(default)] answer: Option<String>, #[serde(default)] citations: Vec<Citation> },
    #[serde(other)]
    Ignored,
}
FrameResult
{"type":"token","text":"…"}Token. A missing text is empty
{"type":"done","answer":"…","citations":[…]}Done. Both fields are optional
Any other typeSkipped (Ignored), so agent can add a new kind of frame without breaking chat
A comment like : ping, or an empty frameSkipped
Not JSONAn error. The exchange ends with agent stream ended unexpectedly

The frames are pinned in schemas/fixtures/agent-stream.json. Its tolerated cases must be survived, so the skipping is a decision, not luck.

async fn step(mut self) -> Option<(anyhow::Result<AgentEvent>, Self)> {
    loop {
        if let Some(event) = self.pending.pop_front() {
            return Some((event, self));
        }
        if self.exhausted {
            return None;
        }

        match self.bytes.next().await {
            Some(Ok(chunk)) => {
                self.buffer.extend_from_slice(&chunk);
                for frame in take_frames(&mut self.buffer) {
                    self.pending.extend(parse_frame(&frame));
                }
            }
            Some(Err(e)) => {
                self.exhausted = true;
                self.pending.push_back(Err(anyhow::Error::new(e)));
            }
            None => self.exhausted = true,
        }
    }
}

The reader works in a loop:

  1. Anything waiting in pending? Hand out the first one.
  2. Exhausted and nothing pending? The stream is over.
  3. Otherwise read the next chunk of bytes, add them to the buffer, cut whole frames, parse each one into pending, and go around again.

A read error becomes an error event, then the stream ends. A clean end of the bytes just ends the stream, and the service above reads the absence of Done as an invalid response.

sequenceDiagram
    autonumber
    participant N as Network
    participant R as SseReader::step
    participant T as take_frames
    participant P as parse_frame
    participant C as Exchange::step
    C->>R: next event?
    R->>R: anything in pending? no
    R->>N: next chunk
    N-->>R: bytes
    R->>R: add to buffer
    R->>T: cut at every blank line
    T-->>R: whole frames, rest stays in buffer
    loop each whole frame
        R->>P: frame bytes
        P->>P: join the data: lines, read JSON
        P-->>R: Token, Done, nothing, or an error
    end
    R-->>C: first pending event

Example, a split frame. Read 1 brings data: {"type":"token","te. Read 2 brings xt":"Room "}\n\n. After read 1 there is no blank line, so nothing is cut and the bytes wait. After read 2 the whole frame is cut and gives Token("Room ").


adapters/driven/persistence/: MongoDB

One collection

pub const CONVERSATIONS: &str = "conversations";

let db_name = options.default_database.clone().unwrap_or_else(|| "chatdb".to_string());
// … two indexes
{ "userId": 1 }
{ "userId": 1, "updatedAt": -1 }

The database name comes from the path of MONGO_URI, else chatdb. Two indexes: one for owner lookups, one to list a person’s conversations newest first.

Messages live inside their conversation:

{"_id": ObjectId("6650c1aa…"), "userId": "3f2b", "title": "Why is room 2 hot?",
 "messages": [
   {"_id": ObjectId("6650c1b0…"), "role": "user", "content": "Why is room 2 hot?", "createdAt": ISODate(…)},
   {"_id": ObjectId("6650c1b1…"), "role": "assistant", "content": "Room 2 reads 31 °C…",
    "citations": [{"chunk_id": "c9", "document_id": "d2", "source": "floor-plans.qd", "section_path": "Rooms"}],
    "createdAt": ISODate(…)}
 ],
 "createdAt": ISODate(…), "updatedAt": ISODate(…)}

Putting messages inside means one write updates both the messages and the conversation. The cost is that the document grows with every message. The 100-message cap keeps it bounded.

Hiding ObjectId

impl From<ConversationDocument> for Conversation {
    fn from(document: ConversationDocument) -> Self {
        Conversation {
            id: document.id.to_hex(),
            user_id: document.user_id,
            title: document.title,
            messages: document.messages.into_iter().map(ChatMessage::from).collect(),
            created_at: iso8601(document.created_at.timestamp_millis()),
            updated_at: iso8601(document.updated_at.timestamp_millis()),
        }
    }
}

Three private “document” types mirror what MongoDB stores (ObjectId, DateTime). Each converts into a domain type: every ObjectId becomes a bare hex string, and every date becomes 2026-11-02T10:15:30.123Z (the JavaScript ISO shape, so the browser contract did not change). This is the only file that knows ObjectId.

Owned lookups

fn owned(user_id: &str, id: &str) -> Option<mongodb::bson::Document> {
    ObjectId::parse_str(id)
        .ok()
        .map(|id| doc! { "_id": { "$eq": id }, "userId": { "$eq": user_id } })
}

Every query on one conversation filters on _id and userId together. Two details:

Someone else’s conversation is also a miss, so the answer is 404 Conversation not found, never 403. A 403 would tell a stranger that the id exists.

Saving an exchange

let mut set = doc! { "updatedAt": now };
if let Some(title) = new_title {
    set.insert("title", title);
}

let outcome = self
    .collection
    .update_one(
        filter,
        doc! {
            "$push": { "messages": { "$each": [to_bson(&user)?, to_bson(&assistant)?] } },
            "$set": set,
        },
    )
    .await?;

match outcome.matched_count {
    0 => Ok(None),
    _ => Ok(Some(assistant.into())),
}

One update_one does it all: $push with $each appends both messages, $set updates updatedAt and, on the first exchange, title. Two sends at the same moment cannot lose each other’s messages, because each $push is applied atomically by MongoDB. updatedAt is set by hand: the list sorts by it, so a write that forgets it would stop the list reordering, with no error. No match (the conversation is gone): None. The user and assistant messages get the same createdAt.


adapters/driving/http_api/: HTTP

Every field, status code and stream frame: Chat API (OpenAPI).

Routes

Router::new()
    .route("/conversations", post(create_conversation).get(list_conversations))
    .route("/conversations/{id}", get(get_conversation).patch(rename_conversation).delete(delete_conversation))
    .route("/conversations/{id}/messages", post(send_message))

All behind the edge at /chat/*. The edge must not buffer: Caddy needs flush_interval -1, or every token arrives at once at the end.

MethodPathWho may callWhat it doesAnswer
GET/health, /metricsAnyoneProbe, Prometheus200
POST/conversationsSigned inNew empty conversation. Optional title201 conversation
GET/conversationsSigned inOwn conversations, newest updatedAt first, no messages{conversations: [...]}
GET/conversations/{id}OwnerOne conversation with every messageconversation
PATCH/conversations/{id}OwnerRename. title requiredconversation
DELETE/conversations/{id}OwnerDelete204
POST/conversations/{id}/messagesOwnerAsk. The answer streams backSSE

Every request goes through two layers: a rate limiter and a metrics layer. The limiter allows 300 requests per minute per client IP, then answers 429. The IP is the rightmost value of x-forwarded-for, the one the edge appended, not one the client could write. A sweep once per minute drops the clients that were idle. (The same file is copied into chat, digital-twin and notification: no shared Rust library holds middleware, so a fix in one copy must be made in all three.)

Who is the owner

impl<S: Send + Sync> FromRequestParts<S> for GatewayClaims {
    type Rejection = DomainError;

    async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result<Self, Self::Rejection> {
        let raw = parts.headers.get(CLAIMS_HEADER)
            .and_then(|header| header.to_str().ok())
            .filter(|raw| !raw.is_empty())
            .ok_or_else(|| unauthorized("Missing authentication token"))?
            .to_string();

        let decoded = decode_claims_header(&raw)
            .ok_or_else(|| unauthorized("Invalid authentication token"))?;
        let payload: ClaimsPayload = serde_json::from_slice(&decoded)
            .map_err(|_| unauthorized("Invalid authentication token"))?;

        let user_id = payload.user_id()
            .ok_or_else(|| unauthorized("Authentication token is missing an account id"))?
            .to_string();

        Ok(GatewayClaims { user_id, raw })
    }
}

An Axum extractor, run before any handler that lists claims: GatewayClaims:

  1. No header, or empty: 401 Missing authentication token.
  2. Not base64 JSON (any of the four base64 alphabets is accepted): 401 Invalid authentication token.
  3. No sub, or blank: 401 Authentication token is missing an account id.
  4. Otherwise user_id = sub. The raw header is kept too, to forward to agent.

Errors have one name

impl DomainError {
    pub fn describe(&self) -> (StatusCode, &'static str, String) {
        match self {
            DomainError::Validation(m) => (StatusCode::BAD_REQUEST, "Validation Error", m.clone()),
            DomainError::Unauthorized(m) => (StatusCode::UNAUTHORIZED, "Unauthorized Error", m.clone()),
            DomainError::NotFound(m) => (StatusCode::NOT_FOUND, "Not Found Error", m.clone()),
            DomainError::Conflict(m) => (StatusCode::CONFLICT, "Conflict Error", m.clone()),
            DomainError::BadGateway(m) => (StatusCode::BAD_GATEWAY, "Bad Gateway Error", m.clone()),
            DomainError::Internal(e) => {
                log::error!("{e:?}");
                (StatusCode::INTERNAL_SERVER_ERROR, "Internal Server Error", INTERNAL_MESSAGE.to_string())
            }
        }
    }
}

One function decides how every failure is named, so the same error reads the same as a status code before the stream, or as an error frame in the middle of it.

VariantStatustypeExample message
Validation400Validation Errorcontent must be a non-empty string
Unauthorized401Unauthorized ErrorMissing authentication token
NotFound404Not Found ErrorConversation not found
Conflict409Conflict ErrorConversation message limit reached
BadGateway502Bad Gateway ErrorCould not reach agent
Internal500Internal Server ErrorA generic text. The real cause is only logged

Reading the body

fn payload(body: Result<Json<Value>, JsonRejection>) -> Value {
    body.map(|Json(value)| value).unwrap_or(Value::Null)
}

A missing or unreadable body is read as empty. The field check then gives its own clear message (content must be a non-empty string) instead of a framework error in another shape.

The streaming handler

fn frame(event: Result<ChatEvent, DomainError>) -> Event {
    let body = match event {
        Ok(ChatEvent::Token(text)) => json!({ "type": "token", "text": text }),
        Ok(ChatEvent::Done(message)) => json!({ "type": "done", "message": message }),
        Err(error) => {
            let (_, error_type, message) = error.describe();
            json!({ "type": "error", "error": error_type, "message": message })
        }
    };
    Event::default().json_data(body).unwrap_or_else(|_| {
        Event::default().data(r#"{"type":"error","error":"Internal Server Error"}"#)
    })
}

pub async fn send_message(
    State(state): State<AppState>,
    claims: GatewayClaims,
    Path(id): Path<String>,
    body: Result<Json<Value>, JsonRejection>,
) -> Result<Sse<impl Stream<Item = Result<Event, Infallible>>>, DomainError> {
    let request = payload(body);
    let events = state
        .conversations
        .send_message(&claims.user_id, &id, text(&request, "content"), &claims.raw)
        .await?;

    Ok(Sse::new(events.map(|event| Ok(frame(event)))).keep_alive(KeepAlive::default()))
}

If the browser goes away, Axum stops reading the stream and drops it. Done is then never reached, so nothing is saved.


Asking a question, end to end

sequenceDiagram
    autonumber
    participant B as Browser
    participant H as send_message
    participant C as Conversations::send_message
    participant DB as MongoDB
    participant A as AgentService::ask
    participant G as agent
    B->>H: POST /conversations/6650c1aa/messages {content}
    H->>C: send_message(user_id, id, content, claims.raw)
    C->>C: validate_text(content, 8000)
    C->>DB: find_owned: {_id, userId}
    DB-->>C: conversation with 4 messages
    C->>C: has_room_for_exchange: 4 + 2 at most 100
    C->>C: recent_history(10)
    C->>A: ask(question, history, header)
    A->>G: POST /ask {question, history, stream: true}
    G-->>A: 200, headers in
    A-->>C: AnswerStream
    C-->>H: stream of ChatEvent
    H-->>B: 200, text/event-stream
    loop each token
        G-->>A: data: {"type":"token","text":"Room "}
        A->>A: take_frames, parse_frame gives Token
        A-->>C: Token
        C->>C: add text to the answer kept in memory
        C-->>B: data: {"type":"token","text":"Room "}
    end
    G-->>A: data: {"type":"done","answer":…,"citations":[…]}
    A-->>C: Done
    C->>C: answer from done wins over the tokens
    C->>DB: append_exchange: push 2 messages, set updatedAt and title
    DB-->>C: stored assistant message
    C-->>B: data: {"type":"done","message":{…}}

Steps 3 to 12 can still fail with a normal status code: the answer has not started. From step 13 on, the 200 is sent, so a failure can only arrive as an error frame.

Data at each step. Example: Ada (sub 3f2b) asks “Why is room 2 hot?” in a conversation called New chat with no messages.

StepData
1{"content":" Why is room 2 hot? "}
3Why is room 2 hot?: trimmed, 18 characters, under 8000
5Conversation 6650c1aa…, title New chat, 0 messages
60 + 2 ≤ 100: there is room
7[]: no history yet
9{"question":"Why is room 2 hot?","history":[],"stream":true} and header x-gateway-claims = Ada’s raw header
14 to 18Tokens Room , 2 reads , 31 °C [1]. Kept in memory: Room 2 reads 31 °C [1]
19{"type":"done","answer":"Room 2 reads 31 °C.","citations":[{"chunk_id":"c9",…}]}
21Stored text is Room 2 reads 31 °C.: the agent removed a citation mark it could not back
22$push user and assistant messages, $set updatedAt = now and title = Why is room 2 hot?
24{"type":"done","message":{"_id":"6650c1b1…","role":"assistant","content":"Room 2 reads 31 °C.","citations":[…],"createdAt":"…"}}

(Ids and times here are made up for the example. The shapes are real.)

Example, the cap. A conversation has 98 messages: 98 + 2 = 100, allowed. Afterwards it has 100: 100 + 2 = 102, so the next ask is 409 Conversation message limit reached, and agent is never called.

Every way it can end

flowchart TD
    S["POST messages"] --> V{"content non-empty, at most 8000?"}
    V -- no --> E400["400"]
    V -- yes --> O{"owned conversation found?"}
    O -- no --> E404["404"]
    O -- yes --> Cap{"room for 2 more?"}
    Cap -- no --> E409["409"]
    Cap -- yes --> Ask{"agent reached and answers 2xx?"}
    Ask -- no --> E502["502 Could not reach agent, or agent returned N"]
    Ask -- yes --> Open["200, stream open"]
    Open --> Next{"next event"}
    Next -- token --> Tok["token frame"] --> Next
    Next -- "unreadable frame or broken connection" --> F1["error frame: agent stream ended unexpectedly"]
    Next -- "stream ends with no done" --> F2["error frame: agent returned an invalid response"]
    Next -- done --> P{"append_exchange"}
    P -- "conversation gone" --> F3["error frame: Conversation not found"]
    P -- "Mongo error" --> F4["error frame: Internal Server Error"]
    P -- stored --> Done["done frame with the stored message"]

None of the error frames stores anything.

RuleWhy
The text is checked before the conversation is loadedA bad request costs no database read
The cap counts the 2 new messagesA conversation of 99 messages would end at 101
History = the last HISTORY_MAX_MESSAGES messages, not exchangesWith 10, the agent sees the last 5 questions and 5 answers
The caller’s own header goes to agentagent checks rights as the user. chat never asks for more than the user may see
Nothing is stored before the done frameA broken answer leaves the conversation as it was
Both messages and the title in one update_oneTwo sends at once cannot lose each other’s messages

The other routes

sequenceDiagram
    autonumber
    participant B as Browser
    participant H as handlers
    participant C as Conversations
    participant DB as MongoDB
    B->>H: POST /conversations {title?}
    H->>C: create(user_id, Absent or Present)
    C->>C: Absent gives New chat, Present is checked
    C->>DB: insert_one
    H-->>B: 201 conversation
    B->>H: GET /conversations
    H->>C: list(user_id)
    C->>DB: find userId, without messages, sort updatedAt -1
    H-->>B: {conversations: [...]}
    B->>H: PATCH /conversations/{id} {title}
    H->>C: rename
    C->>C: validate_text(title, 120)
    C->>DB: find_one_and_update {_id, userId}, set title and updatedAt
    H-->>B: conversation, or 404
    B->>H: DELETE /conversations/{id}
    H->>C: delete
    C->>DB: delete_one {_id, userId}
    H-->>B: 204, or 404

main.rs and configuration

fn history_max_messages() -> usize {
    match env::var("HISTORY_MAX_MESSAGES") {
        Err(_) => DEFAULT_HISTORY_MAX_MESSAGES,
        Ok(raw) => raw
            .parse::<usize>()
            .ok()
            .filter(|value| *value >= 1)
            .unwrap_or_else(|| panic!("HISTORY_MAX_MESSAGES must be a positive integer")),
    }
}

Read once at start. The old Node service re-read and re-checked it on every request, so a bad value only showed up as a 500 on the first message. Now the same mistake is a container that refuses to start. Not set: 10. Set to 0, to a negative number or to text: panic.

main then connects to MongoDB (panic if it cannot), builds Conversations from the Mongo store and the agent client, builds the router, and serves on 0.0.0.0:{PORT} with a graceful shutdown on Ctrl+C or SIGTERM. The connection info is passed (into_make_service_with_connect_info) so the rate limiter can fall back to the peer address.

VariableDefaultWhat it is
MONGO_URImongodb://localhost:27017/chatdbThe database. The name comes from the URI path, else chatdb
AGENT_URLhttp://agent:3000Base of agent’s /ask
HISTORY_MAX_MESSAGES10Messages sent as history. Read once at start. 0 or not a number stops the service at start
PORT3000HTTP port

Fixed in code:

LimitValueApplies to
MAX_MESSAGES100Messages in one conversation
MAX_MESSAGE_LENGTH8000 charactersOne question, after trimming
MAX_TITLE_LENGTH120 charactersA title, after trimming
DEFAULT_TITLENew chatA conversation created without title
Agent connect timeout5 sOpening the connection to agent
Agent read timeout60 sEach wait for the next bytes of the stream
Rate limit300 per minuteRequests per client IP

There is no total timeout on the agent call: a long answer may take minutes. The read timeout still ends a stream that stops sending.

The API shape is pinned in schemas/fixtures/chat-conversation.json. The frontend reads it only through src/utils/commons/chat.ts.


Tests

just test chat               # unit, no infra
just test chat-integration   # tests/*.rs against a throwaway Mongo and a mock agent
WhereWhat it checks
domain/conversation.rsBare string ids. snake_case citations. section_path null. Trim then measure. The cap at 98 and 99. The history window. The title only on the first exchange, cut at 120. The chat-conversation.json fixture round-trips and its rejected cases fail
service/conversations.rsTokens then a stored message. answer wins, else the tokens. An aborted or unterminated stream stores nothing. An unreachable agent fails before the stream. History and header are forwarded. The cap is 409 before the agent. Empty content fails before any load. Someone else’s conversation is 404
adapters/driven/agent.rsEvery agent-stream.json stream decodes as meant. Tolerated frames are survived. A frame split over two reads. A character split over two reads. Several frames in one read. Keep-alive skipped. A bad frame is an error. An early end gives no done
http_api/claims.rs, exceptions.rsThe four 401 cases. URL-safe base64. Each error’s status and name. Internal causes are never shown
tests/api.rsThe same flows over HTTP with a real Mongo: ids, titles, ordering by updatedAt, 404 for strangers and bad ids, a streamed answer stored, a cleaned answer stored, nothing stored on a broken stream
tests/architecture_fitness.rsLayer imports. ObjectId confined. No blanket camelCase. The claims header name

The service tests use service/fakes.rs, in-memory stand-ins for both ports. That is why a streaming exchange can be tested with no Mongo and no agent.


Gaps