Generate the proxy wire types with ts-rs (@yaakapp-internal/send-proxy)

crates-server/yaak-send-proxy/Cargo.toml

@@ -29,6 +29,7 @@ serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 tokio = { workspace = true, features = ["rt-multi-thread", "macros", "signal", "sync", "io-util", "time", "net"] }
 tower-http = { version = "0.6", features = ["cors", "trace"] }
+ts-rs = { workspace = true }
 url = "2"
 uuid = { version = "1", features = ["v4"] }
 yaak-http = { workspace = true }

crates-server/yaak-send-proxy/README.md

@@ -121,6 +121,11 @@ construction, cancellable by closing the connection, readable with `curl`, and
 needs no upgrade handling on either side. A WebSocket only earns its keep when
 traffic is bidirectional, which a single send is not.
 
+The TypeScript side of this contract is generated from `src/wire.rs` by ts-rs
+into `bindings/` (run `cargo test -p yaak-send-proxy` after changing a frame)
+and published to the tab as `@yaakapp-internal/send-proxy`, so a change to the
+wire on one side is a type error on the other.
+
 `GET /v1/health` reports the version and the effective limits.
 
 ## What comes later

crates-server/yaak-send-proxy/bindings/gen_models.ts

@@ -0,0 +1,48 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Cookie = { name: string, value: string, domain: CookieDomain, expires: CookieExpires, path: string, secure: boolean, httpOnly: boolean, sameSite: CookieSameSite | null, };
+
+export type CookieDomain = { "HostOnly": string } | { "Suffix": string } | "NotPresent" | "Empty";
+
+export type CookieExpires = { "AtUtc": string } | "SessionEnd";
+
+export type CookieSameSite = "Strict" | "Lax" | "None";
+
+export type HttpRequest = { model: "http_request", id: string, createdAt: string, updatedAt: string, workspaceId: string, folderId: string | null, authentication: Record<string, any>, authenticationType: string | null, body: Record<string, any>, bodyType: string | null, description: string, headers: Array<HttpRequestHeader>, method: string, name: string, sortPriority: number, url: string, 
+/**
+ * URL parameters used for both path placeholders (`:id`) and query string entries.
+ */
+urlParameters: Array<HttpUrlParameter>, settingSendCookies: InheritedBoolSetting, settingStoreCookies: InheritedBoolSetting, settingValidateCertificates: InheritedBoolSetting, settingFollowRedirects: InheritedBoolSetting, settingRequestTimeout: InheritedIntSetting, };
+
+export type HttpRequestHeader = { enabled?: boolean, name: string, value: string, id?: string, };
+
+/**
+ * Serializable representation of HTTP response events for DB storage.
+ * This mirrors `yaak_http::sender::HttpResponseEvent` but with serde support.
+ * The `From` impl is in yaak-http to avoid circular dependencies.
+ */
+export type HttpResponseEventData = { "type": "setting", name: string, value: string, source_model?: string, source_id?: string, source_name?: string, } | { "type": "info", message: string, } | { "type": "redirect", url: string, status: number, behavior: string, dropped_body: boolean, dropped_headers: Array<string>, } | { "type": "send_url", method: string, scheme: string, username: string, password: string, host: string, port: number, path: string, query: string, fragment: string, } | { "type": "receive_url", version: string, status: string, } | { "type": "header_up", name: string, value: string, } | { "type": "header_down", name: string, value: string, } | { "type": "chunk_sent", bytes: number, } | { "type": "chunk_received", bytes: number, } | { "type": "dns_resolved", hostname: string, addresses: Array<string>, duration: bigint, overridden: boolean, };
+
+export type HttpResponseHeader = { name: string, value: string, };
+
+/**
+ * The resolved send settings, values only: what an executor has to obey, with the sources
+ * (which model each came from) left behind in [`ResolvedHttpRequestSettings`]. This is what
+ * crosses from a tab to the send proxy, and what the proxy reads.
+ */
+export type HttpSendSettings = { validateCertificates: boolean, followRedirects: boolean, 
+/**
+ * Milliseconds. Zero or negative means no timeout.
+ */
+timeoutMs: number, sendCookies: boolean, storeCookies: boolean, };
+
+export type HttpUrlParameter = { enabled?: boolean, 
+/**
+ * Colon-prefixed parameters are treated as path parameters if they match, like `/users/:id`
+ * Other entries are appended as query parameters
+ */
+name: string, value: string, id?: string, };
+
+export type InheritedBoolSetting = { enabled?: boolean, value: boolean, };
+
+export type InheritedIntSetting = { enabled?: boolean, value: number, };

crates-server/yaak-send-proxy/bindings/gen_send_proxy.ts

@@ -0,0 +1,64 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Cookie, HttpRequest, HttpResponseEventData, HttpResponseHeader, HttpSendSettings } from "./gen_models";
+
+/**
+ * One line of the reply stream. Tags are snake_case like the timeline event tags; fields are
+ * camelCase like every model the tab stores.
+ */
+export type Frame = { "type": "event", event: HttpResponseEventData, } | { "type": "response", status: number, statusReason: string | null, 
+/**
+ * The URL that answered, after redirects.
+ */
+url: string, remoteAddr: string | null, version: string | null, headers: Array<HttpResponseHeader>, 
+/**
+ * The headers that were actually sent on the final hop, cookies and all.
+ */
+requestHeaders: Array<HttpResponseHeader>, 
+/**
+ * `Content-Length` as declared by the server, if it declared one.
+ */
+contentLength: number | null, 
+/**
+ * Milliseconds from the start of the send to the response head.
+ */
+elapsedHeaders: number, 
+/**
+ * Milliseconds spent in DNS on the last lookup, or zero.
+ */
+elapsedDns: number, } | { "type": "body", data: string, } | { "type": "done", 
+/**
+ * Milliseconds from the start of the send to the end of the body.
+ */
+elapsed: number, 
+/**
+ * Bytes of body relayed, after decompression.
+ */
+contentLength: number, 
+/**
+ * Bytes on the wire as declared by the server, or the relayed size when unknown.
+ */
+contentLengthCompressed: number, 
+/**
+ * The jar as the send left it, for the tab to persist. `None` when the tab sent none.
+ */
+cookies: Array<Cookie> | null, } | { "type": "error", message: string, cookies: Array<Cookie> | null, };
+
+/**
+ * The body of `POST /v1/http/send`.
+ */
+export type SendRequest = { 
+/**
+ * The request to send, in the desktop's own model shape but with every template already
+ * rendered by the tab. The proxy builds the URL, headers and body from it exactly the way
+ * the desktop does after rendering.
+ */
+request: HttpRequest, 
+/**
+ * The resolved settings, values only. Where they came from is the tab's to record in
+ * its timeline; the proxy only needs to obey them.
+ */
+settings: HttpSendSettings, 
+/**
+ * The cookies to start with. `None` means no jar at all: nothing sent, nothing kept.
+ */
+cookies: Array<Cookie> | null, };

crates-server/yaak-send-proxy/index.ts

@@ -0,0 +1,4 @@
+// The send proxy's wire contract, generated by ts-rs from src/wire.rs
+// (`cargo test -p yaak-send-proxy`). The tab imports these so a change to a
+// frame on the Rust side is a type error in packages/platform/src/web.
+export type { Frame, SendRequest } from "./bindings/gen_send_proxy";

crates-server/yaak-send-proxy/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@yaakapp-internal/send-proxy",
+  "version": "1.0.0",
+  "private": true,
+  "main": "index.ts"
+}

crates-server/yaak-send-proxy/src/wire.rs

@@ -9,15 +9,21 @@
 //! Nothing here names a workspace, a request id, or a response id. The proxy
 //! does not know what the tab will call this response; it only knows what came
 //! back.
+//!
+//! The TypeScript side of this contract is generated from these types into
+//! `bindings/` (`cargo test -p yaak-send-proxy`) and published to the tab as
+//! `@yaakapp-internal/send-proxy`, so a change here is a type error there.
 
 use serde::{Deserialize, Serialize};
+use ts_rs::TS;
 use yaak_models::models::{
     Cookie, HttpRequest, HttpResponseEventData, HttpResponseHeader, HttpSendSettings,
 };
 
 /// The body of `POST /v1/http/send`.
-#[derive(Deserialize, Debug)]
+#[derive(Deserialize, Debug, TS)]
 #[serde(rename_all = "camelCase")]
+#[ts(export, export_to = "gen_send_proxy.ts")]
 pub struct SendRequest {
     /// The request to send, in the desktop's own model shape but with every template already
     /// rendered by the tab. The proxy builds the URL, headers and body from it exactly the way
@@ -33,12 +39,13 @@ pub struct SendRequest {
 
 /// One line of the reply stream. Tags are snake_case like the timeline event tags; fields are
 /// camelCase like every model the tab stores.
-#[derive(Serialize, Debug)]
+#[derive(Serialize, Debug, TS)]
 #[serde(
     tag = "type",
     rename_all = "snake_case",
     rename_all_fields = "camelCase"
 )]
+#[ts(export, export_to = "gen_send_proxy.ts")]
 pub enum Frame {
     /// A timeline event, in the same shape the desktop stores. Interleaved with everything
     /// else in the order the engine produced it.
@@ -56,10 +63,13 @@ pub enum Frame {
         /// The headers that were actually sent on the final hop, cookies and all.
         request_headers: Vec<HttpResponseHeader>,
         /// `Content-Length` as declared by the server, if it declared one.
+        #[ts(type = "number | null")]
         content_length: Option<u64>,
         /// Milliseconds from the start of the send to the response head.
+        #[ts(type = "number")]
         elapsed_headers: u64,
         /// Milliseconds spent in DNS on the last lookup, or zero.
+        #[ts(type = "number")]
         elapsed_dns: u64,
     },
     /// A piece of the response body, decompressed, base64-encoded.
@@ -67,10 +77,13 @@ pub enum Frame {
     /// The send finished. The last frame on a successful stream.
     Done {
         /// Milliseconds from the start of the send to the end of the body.
+        #[ts(type = "number")]
         elapsed: u64,
         /// Bytes of body relayed, after decompression.
+        #[ts(type = "number")]
         content_length: u64,
         /// Bytes on the wire as declared by the server, or the relayed size when unknown.
+        #[ts(type = "number")]
         content_length_compressed: u64,
         /// The jar as the send left it, for the tab to persist. `None` when the tab sent none.
         cookies: Option<Vec<Cookie>>,