//! WebSocket handler for `/task_runs/subscriptions/scheduled` — the //! background-task subscription path. //! //! Protocol (mirrors `src/prefect/server/api/task_runs.py:357`): //! Client → Server: `{"type":"subscribe","keys":[...],"client_id":"..."}` //! Server → Client: task_run JSON, one at a time //! Client → Server: `{"type":"ack"}` after processing //! Client → Server: `{"type":"quit"}` to close cleanly //! //! On send failure or disconnect, the in-flight task_run is pushed back to //! the per-key retry sub-queue (handled in `task_workers.zig`). const std = @import("std"); const wap = @import("wap"); const Allocator = std.mem.Allocator; const json = std.json; const log = @import("../logging.zig"); const task_workers = @import("../task_workers.zig"); const auth_util = @import("auth.zig"); const SubState = enum { waiting_auth, waiting_subscribe, subscribed }; const State = struct { conn: *wap.ws.Conn, allocator: Allocator, state: SubState = .waiting_auth, /// Set once subscribed so on_close can pass the right handle. registered: bool = false, }; fn factory(allocator: Allocator, _: std.Io, _: *const wap.ws.Handshake, conn: *wap.ws.Conn) anyerror!*anyopaque { const s = try allocator.create(State); s.* = .{ .conn = conn, .allocator = allocator }; log.debug("task_runs_subscriptions", "connection opened", .{}); return @ptrCast(s); } fn onMessage(state_ptr: *anyopaque, data: []const u8, _: bool) anyerror!void { const s: *State = @ptrCast(@alignCast(state_ptr)); var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator); defer arena.deinit(); const alloc = arena.allocator(); const parsed = json.parseFromSlice(json.Value, alloc, data, .{}) catch { log.err("task_runs_subscriptions", "invalid json from subscriber", .{}); s.conn.close(.{ .code = 4001, .reason = "Protocol violation: invalid json" }) catch {}; return; }; if (parsed.value != .object) { s.conn.close(.{ .code = 4001, .reason = "Protocol violation: not an object" }) catch {}; return; } const obj = parsed.value.object; const msg_type = if (obj.get("type")) |v| switch (v) { .string => |str| str, else => null, } else null; if (msg_type == null) { log.err("task_runs_subscriptions", "message missing type field", .{}); s.conn.close(.{ .code = 4001, .reason = "Protocol violation: missing type" }) catch {}; return; } switch (s.state) { .waiting_auth => { // Python prefect client sends `{"type":"auth","token":...}` first // on every subscription WebSocket and waits for `auth_success`. // Unauthenticated server: accept any token. Token validation can // wire in here later. if (!std.mem.eql(u8, msg_type.?, "auth")) { log.err("task_runs_subscriptions", "expected 'auth', got {s}", .{msg_type.?}); s.conn.close(.{ .code = 4001, .reason = "Protocol violation: expected 'auth' message" }) catch {}; return; } if (!auth_util.validateSocketAuthFrame(alloc, data, false)) { s.conn.close(.{ .code = 1008, .reason = "authentication_failed" }) catch {}; return; } s.conn.writeText("{\"type\":\"auth_success\"}") catch { log.err("task_runs_subscriptions", "failed to send auth_success", .{}); return; }; s.state = .waiting_subscribe; log.debug("task_runs_subscriptions", "auth handshake done", .{}); }, .waiting_subscribe => { if (!std.mem.eql(u8, msg_type.?, "subscribe")) { log.err("task_runs_subscriptions", "expected 'subscribe', got {s}", .{msg_type.?}); s.conn.close(.{ .code = 4001, .reason = "Protocol violation: expected 'subscribe' message" }) catch {}; return; } const keys_val = obj.get("keys") orelse { s.conn.close(.{ .code = 4001, .reason = "Protocol violation: expected 'keys' in subscribe message" }) catch {}; return; }; if (keys_val != .array or keys_val.array.items.len == 0) { s.conn.close(.{ .code = 4001, .reason = "Protocol violation: 'keys' must be a non-empty array" }) catch {}; return; } const client_id_val = obj.get("client_id") orelse { s.conn.close(.{ .code = 4001, .reason = "Protocol violation: expected 'client_id' in subscribe message" }) catch {}; return; }; if (client_id_val != .string) { s.conn.close(.{ .code = 4001, .reason = "Protocol violation: 'client_id' must be a string" }) catch {}; return; } // collect keys var keys = std.ArrayListUnmanaged([]const u8).empty; for (keys_val.array.items) |k| { if (k == .string) try keys.append(alloc, k.string); } if (keys.items.len == 0) { s.conn.close(.{ .code = 4001, .reason = "Protocol violation: 'keys' had no string entries" }) catch {}; return; } const accepted = task_workers.addSubscriber(s.conn, client_id_val.string, keys.items) catch { s.conn.close(.{ .code = 1011, .reason = "tracker error" }) catch {}; return; }; if (!accepted) { s.conn.close(.{ .code = 1013, .reason = "server at capacity" }) catch {}; return; } s.registered = true; s.state = .subscribed; log.info("task_runs_subscriptions", "client {s} subscribed to {d} key(s)", .{ client_id_val.string, keys.items.len }); }, .subscribed => { if (std.mem.eql(u8, msg_type.?, "ack")) { task_workers.ack(s.conn); return; } if (std.mem.eql(u8, msg_type.?, "quit")) { s.conn.close(.{}) catch {}; return; } log.warn("task_runs_subscriptions", "unexpected message type while subscribed: {s}", .{msg_type.?}); }, } } fn onClose(state_ptr: *anyopaque) void { const s: *State = @ptrCast(@alignCast(state_ptr)); if (s.registered) task_workers.removeSubscriber(s.conn); log.debug("task_runs_subscriptions", "connection closed", .{}); } const routes_table = [_]wap.ws.Route{ .{ .path = "/task_runs/subscriptions/scheduled", .factory = factory, .on_message = onMessage, .on_close = onClose, }, .{ .path = "/api/task_runs/subscriptions/scheduled", .factory = factory, .on_message = onMessage, .on_close = onClose, }, }; pub fn wapRoutes() []const wap.ws.Route { return &routes_table; }