123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477
// Copyright 2022 Connor Logan. All rights reserved. MIT License.// This module is browser-compatible.
import {  packBody,  packJson,  packer,  unpack,  unpackBody,  usePackers,} from "./pack.ts";
import type { Packers } from "./pack.ts";import type { AnyRpc, Parser, ParserInput, Rpc } from "./rpc.ts";import type { Stack } from "./stack.ts";import type { SocketResponse } from "./http.ts";
/** Initializer arguments for constructing HttpErrors. */export interface HttpErrorInit {  /** An HTTP status code describing what kind of error this is. */  status?: number;  /** Optional data exposed to the client when this error is serialized. */  expose?: unknown;  /** Other details about the error. Omitted during serialization. */  detail?: Record<string, unknown>;}
/** An error class for describing exceptions during HTTP processing. */export class HttpError extends Error {  /** An HTTP status code describing what kind of error this is. */  status: number;  /** Optional data exposed to the client when this error is serialized. */  expose?: unknown;  /** Other details about the error. Omitted during serialization. */  detail: Record<string, unknown>;
  constructor(message: string, init?: HttpErrorInit) {    super(message);    this.status = init?.status || 500;    this.expose = init?.expose;    this.detail = init?.detail || {};  }}
usePackers({  httpError: packer({    check: (v) => v instanceof HttpError,    pack: (v: HttpError) => ({      status: v.status,      message: v.message,      expose: v.expose,    }),    unpack: (raw, whenDone) => {      const u = (raw as { status: number; message: string });      const err = new HttpError(u.message, { status: u.status });      whenDone((parsed) => {        err.expose = parsed.expose;      });      return err;    },  }),});
/** * Wrapper interface providing WebSocket functionality with support for typed * messages. */export interface Socket<  O extends unknown = unknown,  I extends unknown = unknown,> {  /** The raw underlying WebSocket instance. */  raw: WebSocket;  /** Send data to the receiver matching the type it expects to receive. */  send(data: O): void;  /** Close the socket connection with an optional code / explanation. */  close(code?: number, reason?: string): void;  /** Register a socket event listener and return the passed-in listener. */  on<    T extends "open" | "message" | "close" | "error",    L extends (      T extends "open" ? (ev: Event) => void | Promise<void>      : T extends "message" ? (        message: I,        ev: MessageEvent,      ) => void | Promise<void>      : T extends "close" ? (ev: CloseEvent) => void | Promise<void>      : T extends "error" ? (        err: unknown,        ev: Event | ErrorEvent,      ) => void | Promise<void>      : never    )  >(    type: T,    listener: L,  ): L;  /** Turn off a listener for a given event type. */  off(    type: "open" | "message" | "close" | "error",    listener: (...a: unknown[]) => void | Promise<void>,  ): void;}
const decoder = new TextDecoder();
type Listener = (...a: unknown[]) => void | Promise<void>;
/** Wraps a regular WebSocket with packing functionality and type support. */export function wrapWebSocket<  O extends unknown = unknown,  I extends unknown = unknown,>(  raw: WebSocket,  init?: {    /** Optionally parse the message further after unpacking it. */    parseMessage?: (message: unknown) => I | Promise<I>;    /** Packers to use when packing and unpacking messages. */    packers?: Packers;  },): Socket<O, I> {  const listeners = {    open: new Set<Listener>(),    message: new Set<Listener>(),    close: new Set<Listener>(),    error: new Set<Listener>(),  };
  raw.addEventListener("open", async ev => {    for (const l of listeners.open.values()) {      try {        await l(ev);      } catch (e) {        raw.dispatchEvent(new ErrorEvent("error", { error: e }));      }    }  });
  raw.addEventListener("message", async ev => {    const data = ev.data;    if (      typeof data !== "string" &&      !ArrayBuffer.isView(data) &&      !(data instanceof Blob)    ) {      // This shouldn't happen unless "they" change what data can be sent over      // sockets in the browser. As of 2-15-22, it should just be ArrayBuffer      // views, strings, and blobs      throw new Error(`Invalid data received: ${data}`);    }
    let message: unknown;    try {      message = unpack((        typeof data === "string" ? data        : ArrayBuffer.isView(data) ? decoder.decode(data)        : await data.text() // Blob      ), init?.packers);    } catch (e) {      raw.dispatchEvent(new ErrorEvent("error", {        error: new HttpError("400 bad request", {          status: 400,          expose: {            reason: "Failed to deserialize web socket message",            error: e,          },        }),      }));      return;    }
    if (init?.parseMessage) {      try {        message = await init.parseMessage(ev.data);      } catch (e) {        // When the server-side socket receives a bad message that doesn't        // parse, the parseMessage call above will take care of sending an error        // response to the client. Then, it'll throw undefined to indicate the        // error got handled but also the message should not continue on to any        // message listeners. When that happens, simply return early        if (typeof e === "undefined") {          return;        }
        // In all other cases, the error is dispatched to the socket error        // listeners before returning        raw.dispatchEvent(new ErrorEvent("error", { error: e }));        return;      }    }
    for (const l of listeners.message.values()) {      try {        await l(message, ev);      } catch (e) {        raw.dispatchEvent(new ErrorEvent("error", { error: e }));      }    }  });
  raw.addEventListener("close", async ev => {    for (const l of listeners.close.values()) {      try {        await l(ev);      } catch (e) {        raw.dispatchEvent(new ErrorEvent("error", { error: e }));      }    }  });
  raw.addEventListener("error", async ev => {    for (const l of listeners.error.values()) {      try {        await l((ev as ErrorEvent).error, ev);      } catch (e) {        console.error(          `ERROR: An error was thrown during a web socket error listener:`,          e,        );      }    }  });
  return {    raw,    send(data) {      raw.send(packJson(data, init?.packers));    },    close(code, reason) {      raw.close(code, reason);    },    on(      type: "open" | "message" | "close" | "error",      listener: Listener,    ) {      listeners[type].add(listener);      return listener;    },    off(      type: "open" | "message" | "close" | "error",      listener: Listener,    ) {      listeners[type].delete(listener);    },  } as Socket;}
/** * A Proxied function that wraps `fetch()` with a tailored process for making * requests to a Cav server. Each property access on the function itself returns * a new Client that extends the URL of the original Client. The periods * represent path dividers and the accessed properties are path segments, like * this: `client("http://localhost/base").nested["pa.th"]()` will result in a * request to "http://localhost/base/nested/pa.th". * * The type parameter is the type of the handler this client points to, which * allows the Client typescript to extract information about what data the Cav * server expects to receive and respond with. Special treatment is given to * Stacks and Rpcs. For now, any other type will result in all argument shapes * and response types to be `unknown`. */export type Client<T = unknown> = (  T extends Stack<infer R> ? Client<R>  : T extends Rpc<    infer R,    // deno-lint-ignore no-explicit-any    any,    // deno-lint-ignore no-explicit-any    any,    infer Q,    infer M,    infer S  > ? Endpoint<R, Q, M, S>  : T extends Record<never, never> ? UnionToIntersection<{    [K in keyof T]: ExpandPath<K, Client<T[K]>>  }[keyof T]>  : unknown);
/** * Client type representing an Rpc endpoint. Uses the Rpc type definition to * determine what the expected arguments and response types are. */export interface Endpoint<  Resp,  Query,  Message,  SocketFlag,  E = EndpointArg<Query, Message, SocketFlag>,> {  (x: { [K in keyof E]: E[K] }): Promise<    Resp extends SocketResponse<infer M> ? (      Message extends Parser ? Socket<ParserInput<Message>, M>      : Socket<unknown, M>    )    : Resp  >;}
/** * Uses the RpcInit type imported from the server to determine what shape the * arguments should be in when making requests to a given Rpc. */export type EndpointArg<  Query,  Message,  SocketFlag,> = Clean<{  /**   * Additional path segments to use when making a request to this endpoint.   * Including extra path should only be done if the Rpc expects it. Default:   * `undefined`   */  path?: string;  /**   * If the Rpc is socket-type, this value should be set to `true`. The returned   * value will be the wrapped web socket. Default: `undefined`   */  socket: SocketFlag extends true ? true : never;  /** The query string parameters expected by the Rpc. Default: `undefined` */  query: ParserInput<Query>;  /** The message expected by the Rpc. Default: `undefined` */  message: ParserInput<Message>;  /**   * Additional packers that should be used while serializing data. Default:   * `undefined`   */  packers?: Packers;}>;
interface CustomFetchArg {  path?: string;  socket?: boolean;  query?: Record<string, string | string[]> | null;  message?: Record<string, unknown>;  packers?: Packers;}
/** * Constructs a new Client tied to a given base URL. The provided set of packers * will be used everywhere that data is packed/unpacked when using this client, * including web sockets. */export function client<T extends Stack | AnyRpc>(  base = "",  packers?: Packers,): Client<T> {  const proxy = (path: string, packers?: Packers): unknown => {    return new Proxy((x: CustomFetchArg) => customFetch(path, {      ...x,      packers: { ...packers, ...x.packers },    }), {      get(_, property) {        if (typeof property !== "string") {          throw new TypeError("Symbol segments can't be used on the client");        }          const append = property.split("/").filter(p => !!p).join("/");        return proxy(path.endsWith("/") ? path + append : path + "/" + append);      }    });  };    const customFetch = async (path: string, x: CustomFetchArg = {}) => {    // If there is an explicit origin in the path, it should override the second    // argument. i.e. the second argument is just a fallback    const url = new URL(path, window.location.origin);    if (x.query) {      for (const [k, v] of Object.entries(x.query)) {        if (Array.isArray(v)) {          for (const v2 of v) {            url.searchParams.append(k, v2);          }        } else {          url.searchParams.append(k, v);        }      }    }      if (x.socket) {      if (url.protocol === "http:") {        url.protocol = "ws:";      } else {        url.protocol = "wss:";      }        const raw = new WebSocket(url.href, "json");      return wrapWebSocket(raw, { packers: x.packers });    }      let body: BodyInit | null = null;    let mime = "";    if (x.message) {      const pb = packBody(x.message, x.packers);      body = pb.body;      mime = pb.mime;    }      const method = body === null ? "GET" : "POST";    const res = await fetch(url.href, {      method,      headers: mime ? { "content-type": mime } : {},      body,    });      let resBody: unknown = undefined;    if (res.body) {      resBody = await unpackBody(res, x.packers);    }      if (!res.ok) {      const detail = { body: resBody };      let message: string;      let status: number;      let expose: unknown;      if (resBody instanceof HttpError) {        message = resBody.message;        status = resBody.status;        expose = resBody.expose;      } else if (typeof resBody === "string") {        message = resBody;        status = res.status;        expose = undefined;      } else {        message = res.statusText;        status = res.status;        expose = undefined;      }      throw new HttpError(message, { status, expose, detail });    }      return resBody;  };
  return proxy(base, packers) as Client<T>;}
/** * Expands the route path from a Stack into an object representing the client * property accesses required to make a successful request for the given route. * Example: `ExpandPath<"hello/world", true>` becomes `{ hello: { world: true } * }` */type ExpandPath<K, T> = (  K extends `*` | `:${string}` ? { [x: string]: T }  : K extends `:${string}/${infer P2}` ? { [x: string]: ExpandPath<P2, T> }  : K extends `/${infer P}` | `${infer P}/` | `${infer P}/*` ? ExpandPath<P, T>  : K extends `${infer P1}/${infer P2}` ? { [x in P1]: ExpandPath<P2, T> }  : K extends string ? { [x in K]: T }  : never);
type Clean<  T,  Required = {    [K in keyof T as (      T[K] extends never ? never      : undefined extends T[K] ? never      : K    )]: T[K];  },  Optional = {    [K in keyof T as (      K extends keyof Required ? never      : T[K] extends never ? never      : K    )]?: T[K];  },> = Required & Optional;
/** * https://fettblog.eu/typescript-union-to-intersection/ */type UnionToIntersection<U> = (  U extends unknown ? (k: U) => void : never) extends ((k: infer I) => void) ? { [K in keyof I]: I[K] } : never