vakya 0.1.0-alpha.1

Completion-native HTTP building blocks for the Karmaio runtime
Documentation
use super::{
    Persistence, UpgradeKind,
    head::{ResponseHead, ValidatedRequestHead, ValidatedResponseHead},
    upgrade_protocols_match,
};
use crate::error::{Error, ErrorKind};
use http::{HeaderValue, Method, header::UPGRADE};

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(super) enum Direction {
    Request,
    Response,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum Progress {
    Active,
    Stopping,
    Complete,
    Aborted,
}

impl Progress {
    fn settled(self) -> bool {
        matches!(self, Self::Complete | Self::Aborted)
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum ResponsePhase {
    AwaitingHead,
    Final,
    Upgrade(UpgradeKind),
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(super) enum HeadAction {
    Informational,
    Final,
    Upgrade(UpgradeKind),
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(super) enum Outcome {
    Active,
    Reusable,
    Close,
    Handoff(UpgradeKind),
}

/// Protocol decisions for one exchange, independent of service-future lifetime.
///
/// A head event is not an I/O-completion event. Drivers must acknowledge both
/// directions only after their framing, producer terminal checks, and owned I/O
/// have settled. An abort requests that work stop; it never asserts that buffers
/// have returned. No transport, body allocation, or scheduling lives here.
#[derive(Debug)]
pub(super) struct Exchange {
    request: Progress,
    response: Progress,
    phase: ResponsePhase,
    persistence: Persistence,
    failed: bool,
    method: Method,
    upgrade: Option<UpgradeKind>,
    offered_protocols: Vec<HeaderValue>,
    informational: usize,
    max_informational: usize,
}

impl Exchange {
    pub(super) fn new(request: &ValidatedRequestHead, max_informational: usize) -> Self {
        Self {
            request: Progress::Active,
            response: Progress::Active,
            phase: ResponsePhase::AwaitingHead,
            persistence: request.persistence,
            failed: false,
            method: request.head.method.clone(),
            upgrade: request.upgrade,
            offered_protocols: if request.upgrade == Some(UpgradeKind::Protocol) {
                request.head.headers.get_all(UPGRADE).iter().cloned().collect()
            } else {
                Vec::new()
            },
            informational: 0,
            max_informational,
        }
    }

    /// Validate a peer response in the context of its request. A final response
    /// does not settle or cancel the upload. Drivers own Expect permission.
    pub(super) fn receive_head(&mut self, head: ResponseHead) -> Result<(ValidatedResponseHead, HeadAction), Error> {
        let result = self.accept_head(head);
        if result.is_err() {
            self.abort();
        }
        result
    }

    fn accept_head(&mut self, head: ResponseHead) -> Result<(ValidatedResponseHead, HeadAction), Error> {
        if self.failed || self.phase != ResponsePhase::AwaitingHead {
            return Err(Error::new(
                ErrorKind::InvalidMessage,
                "response head after final response",
            ));
        }
        let head = head.validate(&self.method)?;
        if let Some(upgrade) = head.upgrade {
            if self.upgrade != Some(upgrade)
                || (upgrade == UpgradeKind::Protocol
                    && !upgrade_protocols_match(&self.offered_protocols, &head.head.headers))
            {
                return Err(Error::new(
                    ErrorKind::Upgrade,
                    "response did not match the requested upgrade",
                ));
            }
            self.phase = ResponsePhase::Upgrade(upgrade);
            return Ok((head, HeadAction::Upgrade(upgrade)));
        }
        if head.head.status.is_informational() {
            if self.informational == self.max_informational {
                return Err(Error::new(ErrorKind::Limit, "too many informational responses"));
            }
            self.informational += 1;
            return Ok((head, HeadAction::Informational));
        }
        self.phase = ResponsePhase::Final;
        if head.persistence == Persistence::Close {
            self.persistence = Persistence::Close;
        }
        Ok((head, HeadAction::Final))
    }

    /// Record a validated final head committed by the server writer. Upload
    /// completion remains independent and is acknowledged through `settle`.
    pub(super) fn sent_final(&mut self, persistence: Persistence) -> Result<(), Error> {
        if self.failed || self.phase != ResponsePhase::AwaitingHead {
            return Err(Error::new(ErrorKind::Internal, "invalid final response transition"));
        }
        self.phase = ResponsePhase::Final;
        if persistence == Persistence::Close {
            self.persistence = Persistence::Close;
        }
        Ok(())
    }

    /// Validate the server's chosen transition before committing any bytes.
    pub(super) fn sent_response(&mut self, head: &ValidatedResponseHead) -> Result<(), Error> {
        if let Some(upgrade) = head.upgrade {
            if self.failed
                || self.phase != ResponsePhase::AwaitingHead
                || self.upgrade != Some(upgrade)
                || (upgrade == UpgradeKind::Protocol
                    && !upgrade_protocols_match(&self.offered_protocols, &head.head.headers))
            {
                return Err(Error::new(
                    ErrorKind::Upgrade,
                    "response did not match the requested upgrade",
                ));
            }

            self.phase = ResponsePhase::Upgrade(upgrade);

            Ok(())
        } else {
            self.sent_final(head.persistence)
        }
    }

    /// Prevent reuse without pretending that outstanding work has completed.
    pub(super) fn close_after_exchange(&mut self) {
        self.persistence = Persistence::Close;
    }

    pub(super) fn abort(&mut self) {
        self.failed = true;
        for progress in [&mut self.request, &mut self.response] {
            if *progress == Progress::Active {
                *progress = Progress::Stopping;
            }
        }
    }

    /// Acknowledge actual direction completion, including any pending operation.
    /// `clean` requires a complete body and successful terminal producer checks.
    pub(super) fn settle(&mut self, direction: Direction, clean: bool) -> Result<(), Error> {
        let progress = match direction {
            Direction::Request => &mut self.request,
            Direction::Response => &mut self.response,
        };
        if progress.settled()
            || (direction == Direction::Response && clean && self.phase == ResponsePhase::AwaitingHead)
        {
            self.abort();
            return Err(Error::new(
                ErrorKind::Internal,
                "invalid exchange completion transition",
            ));
        }
        *progress = if clean { Progress::Complete } else { Progress::Aborted };
        if !clean {
            self.abort();
        }
        Ok(())
    }

    pub(super) fn outcome(&self) -> Outcome {
        if !self.request.settled() || !self.response.settled() {
            return Outcome::Active;
        }
        if self.failed {
            return Outcome::Close;
        }
        if let ResponsePhase::Upgrade(kind) = self.phase {
            return Outcome::Handoff(kind);
        }
        match self.persistence {
            Persistence::Reusable => Outcome::Reusable,
            Persistence::Close => Outcome::Close,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::proto::h1::{
        config::Config,
        head::{HeadParser, RequestRole, ResponseRole},
    };
    use bytes::Bytes;

    fn exchange(wire: &[u8]) -> Exchange {
        let config = Config::default();
        let mut parser = HeadParser::<RequestRole>::request(config.head);
        let consumed = parser.head_len(wire).unwrap().expect("complete request fixture");
        let head = parser.parse_shared(Bytes::copy_from_slice(&wire[..consumed])).unwrap();
        Exchange::new(&head.validate().unwrap(), config.max_informational)
    }

    fn response(wire: &[u8]) -> ResponseHead {
        let mut parser = HeadParser::<ResponseRole>::response(Config::default().head);
        let consumed = parser.head_len(wire).unwrap().expect("complete response fixture");
        parser.parse_shared(Bytes::copy_from_slice(&wire[..consumed])).unwrap()
    }

    #[test]
    fn early_final_preserves_upload_and_reuse_waits_for_both_directions() {
        for status in ["200 OK", "400 Bad Request", "500 Internal Server Error"] {
            for first in [Direction::Request, Direction::Response] {
                let mut state = exchange(
                    b"POST / HTTP/1.1\r\nHost: example.test\r\nContent-Length: 10\r\nExpect: 100-continue\r\n\r\n",
                );
                let (_, action) = state
                    .receive_head(response(
                        format!("HTTP/1.1 {status}\r\nContent-Length: 0\r\n\r\n").as_bytes(),
                    ))
                    .unwrap();
                assert_eq!(action, HeadAction::Final);
                assert_eq!(state.request, Progress::Active);
                state.settle(first, true).unwrap();
                assert_eq!(state.outcome(), Outcome::Active);
                let second = if first == Direction::Request {
                    Direction::Response
                } else {
                    Direction::Request
                };
                state.settle(second, true).unwrap();
                assert_eq!(state.outcome(), Outcome::Reusable);
            }
        }
    }

    #[test]
    fn abort_does_not_claim_completion_or_allow_reuse() {
        let mut state = exchange(b"GET / HTTP/1.1\r\nHost: example.test\r\n\r\n");
        state.abort();
        assert_eq!(state.request, Progress::Stopping);
        assert_eq!(state.response, Progress::Stopping);
        assert_eq!(state.outcome(), Outcome::Active);
        state.settle(Direction::Request, false).unwrap();
        assert_eq!(state.outcome(), Outcome::Active);
        state.settle(Direction::Response, false).unwrap();
        assert_eq!(state.outcome(), Outcome::Close);
    }

    #[test]
    fn informational_ordering_and_budget_are_enforced() {
        let mut state =
            exchange(b"POST / HTTP/1.1\r\nHost: example.test\r\nExpect: 100-continue\r\nContent-Length: 1\r\n\r\n");
        let early = b"HTTP/1.1 103 Early Hints\r\n\r\n";
        assert_eq!(
            state.receive_head(response(early)).unwrap().1,
            HeadAction::Informational
        );
        state.receive_head(response(b"HTTP/1.1 100 Continue\r\n\r\n")).unwrap();
        for _ in 2..16 {
            state.receive_head(response(early)).unwrap();
        }
        assert_eq!(
            state.receive_head(response(early)).unwrap_err().kind(),
            ErrorKind::Limit
        );

        let mut state = exchange(b"GET / HTTP/1.1\r\nHost: example.test\r\n\r\n");
        state
            .receive_head(response(b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n"))
            .unwrap();
        assert_eq!(
            state.receive_head(response(early)).unwrap_err().kind(),
            ErrorKind::InvalidMessage
        );
    }

    #[test]
    fn upgrades_require_matching_intent_and_settled_directions() {
        for (request, reply, kind) in [
            (
                b"GET / HTTP/1.1\r\nHost: example.test\r\nConnection: upgrade\r\nUpgrade: websocket\r\n\r\n".as_slice(),
                b"HTTP/1.1 101 Switching Protocols\r\nConnection: upgrade\r\nUpgrade: websocket\r\n\r\n".as_slice(),
                UpgradeKind::Protocol,
            ),
            (
                b"CONNECT example.test:443 HTTP/1.1\r\nHost: example.test\r\n\r\n".as_slice(),
                b"HTTP/1.1 200 OK\r\n\r\n".as_slice(),
                UpgradeKind::Tunnel,
            ),
        ] {
            let mut state = exchange(request);
            assert_eq!(
                state.receive_head(response(reply)).unwrap().1,
                HeadAction::Upgrade(kind)
            );
            state.settle(Direction::Response, true).unwrap();
            assert_eq!(state.outcome(), Outcome::Active);
            state.settle(Direction::Request, true).unwrap();
            assert_eq!(state.outcome(), Outcome::Handoff(kind));
        }
        for request in [
            b"GET / HTTP/1.1\r\nHost: example.test\r\n\r\n".as_slice(),
            b"GET / HTTP/1.1\r\nHost: example.test\r\nConnection: upgrade\r\nUpgrade: h2c\r\n\r\n".as_slice(),
        ] {
            let mut state = exchange(request);
            assert_eq!(
                state
                    .receive_head(response(
                        b"HTTP/1.1 101 Switching Protocols\r\nConnection: upgrade\r\nUpgrade: websocket\r\n\r\n"
                    ))
                    .unwrap_err()
                    .kind(),
                ErrorKind::Upgrade
            );
        }
    }

    #[test]
    fn close_delimited_and_explicit_close_exchanges_never_reuse() {
        for reply in [
            b"HTTP/1.1 200 OK\r\n\r\n".as_slice(),
            b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\nConnection: close\r\n\r\n".as_slice(),
        ] {
            let mut state = exchange(b"GET / HTTP/1.1\r\nHost: example.test\r\n\r\n");
            state.receive_head(response(reply)).unwrap();
            state.settle(Direction::Request, true).unwrap();
            assert_eq!(state.outcome(), Outcome::Active);
            state.settle(Direction::Response, true).unwrap();
            assert_eq!(state.outcome(), Outcome::Close);
        }
    }
}