//! `Channel` — layer L1 of the communication stack
//! (docs/os-development/communication.md) made concrete. A program holds a
//! channel that speaks a protocol; it does not hold a raw handle and marshal
//! bytes at one. The channel is the answer to "who am I talking to", decided
//! once at establishment, so nothing after that ever routes a party again:
//! every packet's `target` addresses an *object* within the peer already chosen.
//!
//! **Possession of the Channel is the connection.** There is no connect step, no
//! session id, no reconnect handshake — the endpoint capability inside is the
//! whole of the relationship, and it cannot be forged, only handed over. Which
//! also means a channel is a resource: `close` it, or it occupies a handle-table
//! slot for the life of the process.
//!
//! **A dead provider surfaces as `-EPEER`, and the recovery is to re-open.**
//! When the process on the other end exits, the kernel fails calls on its
//! endpoint rather than blocking forever; `call` returns null. The client does
//! not repair the channel — it discards it and opens the name again, which
//! reaches whatever instance the registry now points at. The restart story
//! falls out of the naming layer for free; no protocol needs a reconnect verb.
//!
//! `open` resolves a `/protocol/<name>` path through the kernel VFS router and
//! takes the provider's endpoint from the open reply's capability. **No registry
//! is mounted at `/protocol` yet** — init grows one in P2
//! (docs/os-development/protocol-namespace.md) — so `open` cannot succeed today;
//! it is here so the client half of the conversation is written once, against
//! the shape the registry will answer with.

const std = @import("std");
const ipc = @import("ipc");
const file_system = @import("file-system");
const vfs_protocol = @import("vfs-protocol");
const envelope = @import("envelope");

/// Longest `/protocol/...` path this client marshals. The registry's names are
/// short by construction (a contract leaf, not a file path), and the buffer is
/// on the stack of whoever opens.
pub const path_maximum: usize = 224;

/// What a `call` came back with: the provider's status, the reply payload (the
/// bytes after the `Status`, in the caller's own buffer), and any capability the
/// reply carried.
pub const Response = struct {
    status: envelope.Status,
    payload: []u8,
    capability: ?ipc.Handle,

    /// Whether the provider answered success. A negative status is its refusal
    /// (`-ENOSYS` for a verb it does not implement, and so on).
    pub fn succeeded(self: Response) bool {
        return self.status.status == 0;
    }
};

/// An open conversation with one provider, speaking one protocol.
pub const Channel = struct {
    /// The provider's endpoint. Sending into it is the only thing this handle
    /// can do — an endpoint is a mailbox owned by its creator, and that
    /// direction never reverses.
    endpoint: ipc.Handle,

    /// Adopt an endpoint that arrived some other way — a capability delivered
    /// in a reply, or one a supervisor wired in at spawn time (P5). The channel
    /// takes ownership of the handle.
    pub fn adopt(endpoint: ipc.Handle) Channel {
        return .{ .endpoint = endpoint };
    }

    /// Establish a channel by name: resolve `/protocol/<name>` to the registry
    /// backend, `open` the contract there, and take the provider's endpoint from
    /// the reply's capability. Null if the path does not resolve, the registry
    /// refuses (an ungranted name is refused *as* not-found), or the reply
    /// carries no capability.
    ///
    /// The path is spoken exactly once, here. Everything afterwards is integers
    /// in the packet header.
    pub fn open(path: []const u8) ?Channel {
        var relative: [path_maximum]u8 = undefined;
        const route = file_system.fsResolve(path, 0, &relative) orelse return null;
        // A protocol name must land on a mounted backend. The kernel-served
        // `/system` tree answers with a node token and knows nothing of
        // channels, so that route is simply the wrong path.
        const backend = switch (route) {
            .kernel => return null,
            .backend => |b| b,
        };
        // The registry handle is deduplicated by the kernel across resolves and
        // shared with every other user of that mount, so it is not ours to
        // close — only the provider endpoint below belongs to this channel.
        const name = relative[0..backend.path_len];

        var request: [vfs_protocol.message_maximum]u8 = undefined;
        const header = vfs_protocol.Request{
            .operation = .open,
            .node = 0,
            .offset = 0,
            .len = @intCast(name.len),
            .flags = 0,
        };
        if (vfs_protocol.request_size + name.len > request.len) return null;
        @memcpy(request[0..vfs_protocol.request_size], std.mem.asBytes(&header));
        @memcpy(request[vfs_protocol.request_size..][0..name.len], name);

        var reply: [vfs_protocol.message_maximum]u8 = undefined;
        const answer = ipc.callCap(backend.handle, request[0 .. vfs_protocol.request_size + name.len], &reply, null) catch return null;
        if (answer.len < vfs_protocol.reply_size) return null;
        const decoded = std.mem.bytesToValue(vfs_protocol.Reply, reply[0..vfs_protocol.reply_size]);
        if (decoded.status != 0) return null;
        // The capability *is* the channel — an open that succeeds without one
        // was answered by a file backend, which does not speak protocols.
        const provider = answer.cap orelse return null;
        return .{ .endpoint = provider };
    }

    /// Send one request packet and block for the reply: `[Header][request]` out,
    /// `[Status][reply]` back. `request` is the bytes *after* the header — the
    /// protocol's fixed part plus any tail — because the header is this call's
    /// to lay down. The reply's payload lands in `into`.
    ///
    /// Null means the transport failed, which today means one of: a dead
    /// provider (`-EPEER` — discard this channel and `open` the name again), an
    /// oversized packet, or a bad handle. A provider that answered *and refused*
    /// is not a failure here: it comes back with a negative `Response.status`.
    pub fn call(self: Channel, header: envelope.Header, request: []const u8, into: []u8) ?Response {
        return self.callCapability(header, request, into, null);
    }

    /// As `call`, handing the provider a capability with the request — the only
    /// direction-crossing move kernel-ipc offers, and how `subscribe` delivers
    /// the subscriber's own endpoint.
    pub fn callCapability(
        self: Channel,
        header: envelope.Header,
        request: []const u8,
        into: []u8,
        capability: ?ipc.Handle,
    ) ?Response {
        var packet: [envelope.packet_maximum]u8 = undefined;
        const framed = frame(header, request, &packet) orelse return null;

        var reply: [envelope.packet_maximum]u8 = undefined;
        const answer = ipc.callCap(self.endpoint, framed, &reply, capability) catch return null;
        const status = envelope.statusOf(reply[0..answer.len]) orelse return null;
        const available = @min(answer.len - envelope.prefix_size, @as(usize, status.len));
        const taken = @min(available, into.len);
        @memcpy(into[0..taken], reply[envelope.prefix_size..][0..taken]);
        return .{ .status = status, .payload = into[0..taken], .capability = answer.cap };
    }

    /// Push one event packet and return immediately — no reply owed, and a slow
    /// or dead peer can never stall the sender. Bounded by `post_maximum`: an
    /// event that does not fit is refused here rather than split, because a
    /// packet is never fragmented.
    pub fn send(self: Channel, header: envelope.Header, payload: []const u8) bool {
        var packet: [envelope.post_maximum]u8 = undefined;
        const framed = frame(header, payload, &packet) orelse return false;
        return ipc.send(self.endpoint, framed);
    }

    /// Ask the provider what it is: the reserved `describe` verb, answered by
    /// every protocol built through `envelope.Define`. The name and version come
    /// back in `into`, which the returned `Described` borrows.
    pub fn describe(self: Channel, into: []u8) ?envelope.Described {
        var request: [envelope.packet_maximum]u8 = undefined;
        const packet = envelope.encodeDescribe(&request) orelse return null;

        var reply: [envelope.packet_maximum]u8 = undefined;
        const answer = ipc.callCap(self.endpoint, packet, &reply, null) catch return null;
        const taken = @min(answer.len, into.len);
        @memcpy(into[0..taken], reply[0..taken]);
        return envelope.decodeDescribe(into[0..taken]);
    }

    /// Drop the provider's endpoint and free the handle-table slot. The
    /// conversation is over the moment the capability is gone — there is nothing
    /// else holding it open.
    pub fn close(self: Channel) void {
        _ = ipc.close(self.endpoint);
    }
};

/// Lay a packet down: the folded header first, then the protocol's bytes. Null
/// when it would not fit the buffer — the same rule as `envelope`'s framing,
/// applied where the buffer is the transport's, not the protocol's.
fn frame(header: envelope.Header, body: []const u8, buffer: []u8) ?[]u8 {
    const total = envelope.prefix_size + body.len;
    if (total > buffer.len) return null;
    @memcpy(buffer[0..envelope.prefix_size], std.mem.asBytes(&header));
    @memcpy(buffer[envelope.prefix_size..][0..body.len], body);
    return buffer[0..total];
}

// --- tests ------------------------------------------------------------------
//
// The syscall half cannot run on the host, and there is no registry to reach
// until P2 — so what is testable here is the framing, which is the part with
// arithmetic in it.

const testing = std.testing;

test "a framed packet is the header followed by the protocol's bytes" {
    var buffer: [envelope.packet_maximum]u8 = undefined;
    const header = envelope.Header{ .operation = envelope.first_protocol_operation, .target = 9 };
    const packet = frame(header, "body", &buffer).?;

    try testing.expectEqual(envelope.prefix_size + "body".len, packet.len);
    const decoded = envelope.headerOf(packet).?;
    try testing.expectEqual(envelope.first_protocol_operation, decoded.operation);
    try testing.expectEqual(@as(u64, 9), decoded.target);
    try testing.expectEqualStrings("body", packet[envelope.prefix_size..]);
}

test "framing refuses a packet that would not fit rather than truncating it" {
    var post: [envelope.post_maximum]u8 = undefined;
    const header = envelope.Header{ .operation = envelope.first_protocol_operation };
    const body = [_]u8{0} ** (envelope.post_maximum - envelope.prefix_size);
    const one_too_many = body ++ [_]u8{0};

    try testing.expect(frame(header, &body, &post) != null);
    try testing.expect(frame(header, &one_too_many, &post) == null);
}