Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
16.2 KB
Raw Blame
//! Minimal WebSocket client (RFC 6455) for the codex/ChatGPT Responses API
//! over WebSocket (`wss://chatgpt.com/backend-api/codex/responses`) — OpenAI's
//! codex prefers ws and falls back to SSE, and a persistent ws connection also
//! sidesteps the keep-alive `HttpConnectionClosing` retries the SSE path hits.
//! Ported from the mobile-relay daemon's client (src/relay.zig on the
//! mobile-relay branch), with two additions for this use: custom handshake
//! headers (Authorization / OpenAI-Beta / chatgpt-account-id / …) and an
//! upgrade-failure signal (error.UpgradeRequired) so the caller can fall back
//! to SSE. Just what a request/response turn needs: text frames, client
//! masking, ping/pong, close, fragmentation reassembly, one message in / one
//! stream of events out.
//!
//! Observability: set `g_debug = true` (GRAFF_WS_DEBUG=1) to trace the
//! handshake + every frame to stderr; the transport layer additionally routes
//! structured ws lifecycle events to the run's file under .graff/traces so an
//! agent can debug a ws turn after the fact.

const std = @import("std");
const Io = std.Io;
const net = std.Io.net;
const HostName = net.HostName;
const Allocator = std.mem.Allocator;
const tls = std.crypto.tls;
const http_warm = @import("http_warm.zig");

/// GRAFF_WS_DEBUG=1 → dump the handshake + frame headers to stderr.
pub var g_debug: bool = false;
/// Deterministic integration-test seam: fail the next WS connect so the live
/// binary can prove its clean retry against the real endpoint.
pub var g_force_connect_failure_once: bool = false;
/// Counted sibling used to prove the second consecutive failure latches SSE.
pub var g_force_connect_failure_count: u8 = 0;

fn dbg(comptime fmt: []const u8, args: anytype) void {
    if (g_debug) std.debug.print("[ws] " ++ fmt ++ "\n", args);
}

pub const Header = struct { name: []const u8, value: []const u8 };

pub const Opcode = enum(u4) {
    cont = 0x0,
    text = 0x1,
    binary = 0x2,
    close = 0x8,
    ping = 0x9,
    pong = 0xA,
    _,
};

pub const Error = error{
    BadUrl,
    HandshakeFailed,
    /// Server declined the upgrade (e.g. 426) — the caller should fall back to SSE.
    UpgradeRequired,
    PeerClosed,
    MessageTooLong,
    StreamTooLong,
} || Allocator.Error || Io.Reader.Error || Io.Writer.Error;

// Encrypted/raw socket buffers (TLS asserts these are >= tls min_buffer_len).
const sock_buf_cap = 64 * 1024;
// Plaintext TLS buffers.
const tls_buf_cap = 64 * 1024;
/// Hard cap on one reassembled inbound message (a single Responses event).
/// The SSE cap too: 4 MiB refused a compaction item's opaque state, so the
/// turn was retried on a fresh socket and then SSE, each re-running it.
const message_cap = @import("stream_read_progress.zig").max_event_bytes;

comptime {
    if (sock_buf_cap < tls.max_ciphertext_record_len) @compileError("sock_buf_cap < tls min_buffer_len");
}

pub const WsClient = struct {
    io: Io,
    stream: net.Stream,
    rd: net.Stream.Reader,
    wr: net.Stream.Writer,
    // Active plaintext interfaces: raw stream for ws://, TLS plaintext for wss://.
    r: *Io.Reader = undefined,
    w: *Io.Writer = undefined,
    tls_client: ?tls.Client = null,
    gpa: Allocator,
    /// (#401) The peer is wedged or gone — tear down with a plain FIN instead
    /// of deinit's courtesy close frame, which is another blocking write on the
    /// very socket that just proved it won't drain (it would re-hang the
    /// recovery path that is trying to abandon this connection).
    dead: bool = false,
    sock_rbuf: [sock_buf_cap]u8 = undefined,
    sock_wbuf: [sock_buf_cap]u8 = undefined,
    tls_rbuf: [tls_buf_cap]u8 = undefined,
    tls_wbuf: [tls_buf_cap]u8 = undefined,

    /// Connect + (for wss) TLS handshake + the HTTP Upgrade handshake, sending
    /// `headers` as extra request headers. Heap-allocated and stable (the
    /// Reader/Writer interfaces and the TLS client reference its inline buffers
    /// and each other).
    pub fn connect(gpa: Allocator, io: Io, url: []const u8, insecure: bool, headers: []const Header) Error!*WsClient {
        if (g_force_connect_failure_count > 0) {
            g_force_connect_failure_count -= 1;
            dbg("forced connect failure (GRAFF_WS_FORCE_FAIL_COUNT)", .{});
            return error.HandshakeFailed;
        }
        if (g_force_connect_failure_once) {
            g_force_connect_failure_once = false;
            dbg("forced connect failure (GRAFF_WS_FORCE_FAIL_ONCE)", .{});
            return error.HandshakeFailed;
        }
        const u = parseUrl(url) orelse return error.BadUrl;
        dbg("connect {s} host={s} port={d} path={s} tls={}", .{ url, u.host, u.port, u.path, u.tls });

        // DNS + connect. IpAddress.resolve only parses IP literals, so a
        // hostname (chatgpt.com) needs HostName.connect, which looks it up.
        const host_name = HostName.init(u.host) catch |e| {
            dbg("bad host {s}: {s}", .{ u.host, @errorName(e) });
            return error.BadUrl;
        };
        const stream = host_name.connect(io, u.port, .{ .mode = .stream }) catch |e| {
            dbg("connect {s}:{d} failed: {s}", .{ u.host, u.port, @errorName(e) });
            return error.HandshakeFailed;
        };

        const self = try gpa.create(WsClient);
        errdefer gpa.destroy(self);
        self.* = .{ .io = io, .stream = stream, .rd = undefined, .wr = undefined, .gpa = gpa };
        self.rd = net.Stream.Reader.init(stream, io, &self.sock_rbuf);
        self.wr = net.Stream.Writer.init(stream, io, &self.sock_wbuf);
        // From here the client owns the socket: release it if the TLS or
        // upgrade handshake fails, or every failed dial leaks an fd — which
        // #401's reconnect ladder now retries into. The CA bundle is the
        // process-warmed one (http_warm); do not deinit it here.
        errdefer self.stream.close(io);

        if (u.tls) {
            var entropy: [tls.Client.Options.entropy_len]u8 = undefined;
            io.random(&entropy);
            if (!insecure) http_warm.ensureProcessCa(io) catch |e| {
                dbg("ca rescan failed: {s}", .{@errorName(e)});
                return error.HandshakeFailed;
            };
            self.tls_client = tls.Client.init(&self.rd.interface, &self.wr.interface, .{
                .host = if (insecure) .no_verification else .{ .explicit = u.host },
                .ca = if (insecure) .no_verification else .{ .bundle = .{
                    .gpa = std.heap.page_allocator,
                    .io = io,
                    .lock = http_warm.processCaLock(),
                    .bundle = http_warm.processCa(),
                } },
                .write_buffer = &self.tls_wbuf,
                .read_buffer = &self.tls_rbuf,
                .entropy = &entropy,
                .realtime_now = Io.Clock.real.now(io),
            }) catch |e| {
                dbg("tls init failed: {s}", .{@errorName(e)});
                return error.HandshakeFailed;
            };
            self.r = &self.tls_client.?.reader;
            self.w = &self.tls_client.?.writer;
        } else {
            self.r = &self.rd.interface;
            self.w = &self.wr.interface;
        }

        try self.handshake(u, headers);
        return self;
    }

    pub fn deinit(self: *WsClient, gpa: Allocator) void {
        if (!self.dead) self.sendFrame(.close, "") catch {}; // (#401) see `dead`
        self.stream.close(self.io);
        gpa.destroy(self);
    }

    /// Send one text message.
    pub fn sendText(self: *WsClient, payload: []const u8) Error!void {
        dbg("send text {d}b", .{payload.len});
        return self.sendFrame(.text, payload);
    }

    /// Read one complete (re-assembled) message into `out`. Control frames
    /// (ping/pong/close) are handled internally; a peer close → error.PeerClosed.
    /// Returns the message opcode (.text or .binary).
    pub fn readMessage(self: *WsClient, gpa: Allocator, out: *std.ArrayList(u8)) Error!Opcode {
        out.clearRetainingCapacity();
        var msg_op: ?Opcode = null;
        const r = self.r;
        while (true) {
            const h = try r.takeArray(2);
            const fin = (h[0] & 0x80) != 0;
            const op: Opcode = @fromBackingInt(@intCast(@as(u4, @truncate(h[0] & 0x0f))));
            const masked = (h[1] & 0x80) != 0;
            var len: u64 = @as(u64, h[1] & 0x7f);
            if (len == 126) {
                len = std.mem.readInt(u16, try r.takeArray(2), .big);
            } else if (len == 127) {
                len = std.mem.readInt(u64, try r.takeArray(8), .big);
            }
            var mask: [4]u8 = .{ 0, 0, 0, 0 };
            if (masked) mask = (try r.takeArray(4)).*;

            switch (op) {
                .ping => {
                    const p = try r.take(@intCast(len));
                    if (masked) unmask(p, mask);
                    try self.sendFrame(.pong, p);
                    continue;
                },
                .pong => {
                    try r.discardAll(@intCast(len));
                    continue;
                },
                .close => {
                    try r.discardAll(@intCast(len));
                    self.sendFrame(.close, "") catch {};
                    return error.PeerClosed;
                },
                .text, .binary, .cont => {
                    if (out.items.len + len > message_cap) return error.MessageTooLong;
                    const start = out.items.len;
                    try out.resize(gpa, start + @as(usize, @intCast(len)));
                    try r.readSliceAll(out.items[start..]);
                    if (masked) unmask(out.items[start..], mask);
                    if (msg_op == null and op != .cont) msg_op = op;
                    if (fin) {
                        dbg("recv msg {d}b op={s}", .{ out.items.len, @tagName(msg_op orelse .text) });
                        return msg_op orelse .text;
                    }
                },
                else => return error.HandshakeFailed, // unknown opcode
            }
        }
    }

    // ── internals ────────────────────────────────────────────────────────────

    fn handshake(self: *WsClient, u: Url, headers: []const Header) Error!void {
        var key_raw: [16]u8 = undefined;
        self.io.random(&key_raw);
        var key_b64: [24]u8 = undefined;
        _ = std.base64.standard.Encoder.encode(&key_b64, &key_raw);

        try self.w.print(
            "GET {s} HTTP/1.1\r\nHost: {s}\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n" ++
                "Sec-WebSocket-Key: {s}\r\nSec-WebSocket-Version: 13\r\n",
            .{ u.path, u.host, &key_b64 },
        );
        for (headers) |hd| try self.w.print("{s}: {s}\r\n", .{ hd.name, hd.value });
        try self.w.writeAll("\r\n");
        try self.flushTransport();

        // status line: expect "HTTP/1.1 101 ..."; anything else is a rejection.
        const status = try self.r.takeDelimiterInclusive('\n');
        dbg("handshake <- {s}", .{std.mem.trimEnd(u8, status, "\r\n")});
        if (std.mem.indexOf(u8, status, " 101 ") == null) {
            // A 426 (or any non-101) means the server won't upgrade — fall back to SSE.
            return if (std.mem.indexOf(u8, status, " 426 ") != null) error.UpgradeRequired else error.HandshakeFailed;
        }
        // drain headers until the blank line
        while (true) {
            const line = try self.r.takeDelimiterInclusive('\n');
            if (line.len <= 2) break; // "\r\n" or "\n"
        }
    }

    fn flushTransport(self: *WsClient) Error!void {
        try self.w.flush(); // for TLS this encrypts plaintext into the socket writer…
        if (self.tls_client != null) try self.wr.interface.flush(); // …then push the socket buffer
    }

    fn sendFrame(self: *WsClient, op: Opcode, payload: []const u8) Error!void {
        var hdr: [14]u8 = undefined;
        hdr[0] = 0x80 | @as(u8, @backingInt(op)); // FIN + opcode
        var n: usize = 2;
        if (payload.len < 126) {
            hdr[1] = 0x80 | @as(u8, @intCast(payload.len));
        } else if (payload.len <= 0xffff) {
            hdr[1] = 0x80 | 126;
            std.mem.writeInt(u16, hdr[2..4], @intCast(payload.len), .big);
            n = 4;
        } else {
            hdr[1] = 0x80 | 127;
            std.mem.writeInt(u64, hdr[2..10], payload.len, .big);
            n = 10;
        }
        var mask: [4]u8 = undefined;
        self.io.random(&mask);
        @memcpy(hdr[n .. n + 4], &mask);
        n += 4;

        try self.w.writeAll(hdr[0..n]);
        var i: usize = 0;
        var tmp: [4096]u8 = undefined;
        while (i < payload.len) {
            const chunk = @min(tmp.len, payload.len - i);
            for (0..chunk) |j| tmp[j] = payload[i + j] ^ mask[(i + j) & 3];
            try self.w.writeAll(tmp[0..chunk]);
            i += chunk;
        }
        try self.flushTransport();
    }
};

fn unmask(buf: []u8, mask: [4]u8) void {
    for (buf, 0..) |*b, i| b.* ^= mask[i & 3];
}

const Url = struct { tls: bool, host: []const u8, port: u16, path: []const u8 };

fn parseUrl(url: []const u8) ?Url {
    var rest = url;
    var is_tls = false;
    if (std.mem.startsWith(u8, rest, "wss://")) {
        is_tls = true;
        rest = rest["wss://".len..];
    } else if (std.mem.startsWith(u8, rest, "ws://")) {
        rest = rest["ws://".len..];
    } else return null;

    const slash = std.mem.indexOfScalar(u8, rest, '/');
    const authority = if (slash) |s| rest[0..s] else rest;
    const path = if (slash) |s| rest[s..] else "/";
    if (authority.len == 0) return null;

    var host = authority;
    var port: u16 = if (is_tls) 443 else 80;
    if (std.mem.lastIndexOfScalar(u8, authority, ':')) |c| {
        host = authority[0..c];
        port = std.fmt.parseInt(u16, authority[c + 1 ..], 10) catch return null;
    }
    return .{ .tls = is_tls, .host = host, .port = port, .path = path };
}

test "parseUrl: wss/ws, default ports, path" {
    const a = parseUrl("wss://chatgpt.com/backend-api/codex/responses").?;
    try std.testing.expect(a.tls);
    try std.testing.expectEqualStrings("chatgpt.com", a.host);
    try std.testing.expectEqual(@as(u16, 443), a.port);
    try std.testing.expectEqualStrings("/backend-api/codex/responses", a.path);
    const b = parseUrl("ws://localhost:8080/x").?;
    try std.testing.expect(!b.tls);
    try std.testing.expectEqual(@as(u16, 8080), b.port);
    try std.testing.expect(parseUrl("https://nope") == null);
}

test "forced WS failure is one-shot for SSE fallback integration tests" {
    g_force_connect_failure_once = true;
    try std.testing.expectError(error.HandshakeFailed, WsClient.connect(
        std.testing.allocator,
        std.testing.io,
        "wss://unused.invalid/x",
        false,
        &.{},
    ));
    try std.testing.expect(!g_force_connect_failure_once);
}

test "counted forced WS failures exhaust exactly" {
    g_force_connect_failure_count = 2;
    inline for (0..2) |_| try std.testing.expectError(error.HandshakeFailed, WsClient.connect(
        std.testing.allocator,
        std.testing.io,
        "wss://unused.invalid/x",
        false,
        &.{},
    ));
    try std.testing.expectEqual(@as(u8, 0), g_force_connect_failure_count);
}

test "an inbound message may carry a compaction item's multi-megabyte state" {
    const gpa = std.testing.allocator;
    const len: usize = 5 * 1024 * 1024; // over the old 4 MiB cap
    const frame = try gpa.alloc(u8, 10 + len);
    defer gpa.free(frame);
    frame[0] = 0x81; // FIN | text
    frame[1] = 127;
    std.mem.writeInt(u64, frame[2..10], len, .big);
    @memset(frame[10..], 'x');
    var reader: Io.Reader = .fixed(frame);
    var client: WsClient = undefined;
    client.r = &reader;
    var out: std.ArrayList(u8) = .empty;
    defer out.deinit(gpa);
    try std.testing.expectEqual(Opcode.text, try client.readMessage(gpa, &out));
    try std.testing.expectEqual(len, out.items.len);

    // A header claiming more than the cap is refused before any allocation.
    var oversized: [10]u8 = undefined;
    oversized[0] = 0x81;
    oversized[1] = 127;
    std.mem.writeInt(u64, oversized[2..10], message_cap + 1, .big);
    var over_reader: Io.Reader = .fixed(&oversized);
    client.r = &over_reader;
    try std.testing.expectError(error.MessageTooLong, client.readMessage(gpa, &out));
}