@mygo-plugins/websocket 0.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyGo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @mygo-plugins/websocket
+
+A `WebSocket` for [MyGo](https://github.com/egoist/mygo) apps whose
+connections Go makes, with the API of the browser's. Unlike the browser's,
+it may send any header with the opening handshake, such as Authorization,
+Cookie or Origin, and is not subject to the page's Content Security Policy.
+
+Use the plugin in Go:
+
+```go
+import "github.com/egoist/mygo/plugins/websocket"
+
+mygo.Use(websocket.Plugin) // or websocket.New(websocket.Options{...})
+```
+
+and connect in the frontend:
+
+```ts
+import { WebSocket } from "@mygo-plugins/websocket";
+
+const ws = new WebSocket("wss://example.com/live", ["v1"], {
+  headers: { authorization: `Bearer ${token}` },
+});
+ws.onopen = () => ws.send("hello");
+ws.onmessage = (e) => console.log(e.data);
+ws.onclose = (e) => console.log(e.code, e.reason, e.wasClean);
+```
+
+Messages are sent in order, `bufferedAmount` counts the bytes Go has not
+written yet, and received messages wait in Go while the page is behind, so a
+fast server cannot fill the page's memory. Connections close (1001, going
+away) when their page navigates away or its window closes. No extensions
+(such as permessage-deflate) are negotiated.

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/** Options of a {@link WebSocket}, beyond the browser's. */
+export interface WebSocketOptions {
+    /** Headers of the opening handshake, e.g. Authorization or Origin. */
+    headers?: HeadersInit;
+}
+export interface WebSocketEventMap {
+    open: Event;
+    message: MessageEvent;
+    error: Event;
+    close: CloseEvent;
+}
+type Handler<E> = ((this: WebSocket, ev: E) => unknown) | null;
+/**
+ * A WebSocket connection made by Go, with the API of the browser's
+ * `WebSocket`. The third argument sets headers of the opening handshake.
+ */
+export declare class WebSocket extends EventTarget {
+    #private;
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+    /** The URL of the connection, with a ws: or wss: scheme. */
+    readonly url: string;
+    /** How binary messages arrive: as a `Blob`, or an `ArrayBuffer`. */
+    binaryType: BinaryType;
+    constructor(url: string | URL, protocols?: string | string[], options?: WebSocketOptions);
+    /** The state of the connection: CONNECTING, OPEN, CLOSING or CLOSED. */
+    get readyState(): number;
+    /** The subprotocol the server chose, once open. */
+    get protocol(): string;
+    /** The extensions in use: none. */
+    get extensions(): string;
+    /** Bytes sent with `send` that Go has not written yet. */
+    get bufferedAmount(): number;
+    get onopen(): Handler<Event>;
+    set onopen(fn: Handler<Event>);
+    get onmessage(): Handler<MessageEvent>;
+    set onmessage(fn: Handler<MessageEvent>);
+    get onerror(): Handler<Event>;
+    set onerror(fn: Handler<Event>);
+    get onclose(): Handler<CloseEvent>;
+    set onclose(fn: Handler<CloseEvent>);
+    /** Sends a message: text, or binary data. Throws while connecting. */
+    send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+    /**
+     * Closes the connection with a code (1000, or 3000 to 4999) and a reason
+     * of at most 123 bytes.
+     */
+    close(code?: number, reason?: string): void;
+}
+export interface WebSocket {
+    addEventListener<K extends keyof WebSocketEventMap>(type: K, listener: (this: WebSocket, ev: WebSocketEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof WebSocketEventMap>(type: K, listener: (this: WebSocket, ev: WebSocketEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
+}
+export default WebSocket;

package/dist/index.js

@@ -0,0 +1,225 @@
+// src/index.ts
+import { Channel, call, isCallError } from "mygo-runtime";
+var CONNECTING = 0;
+var OPEN = 1;
+var CLOSING = 2;
+var CLOSED = 3;
+var encoder = new TextEncoder;
+
+class WebSocket extends EventTarget {
+  static CONNECTING = CONNECTING;
+  static OPEN = OPEN;
+  static CLOSING = CLOSING;
+  static CLOSED = CLOSED;
+  url;
+  binaryType = "blob";
+  #id;
+  #state = CONNECTING;
+  #protocol = "";
+  #buffered = 0;
+  #seq = 0;
+  #failed;
+  #events;
+  #handlers = new Map;
+  constructor(url, protocols = [], options = {}) {
+    super();
+    const base = typeof location !== "undefined" ? location.href : undefined;
+    let u;
+    try {
+      u = new URL(url, base);
+    } catch {
+      throw new DOMException(`Invalid URL: ${url}`, "SyntaxError");
+    }
+    if (u.protocol === "http:")
+      u.protocol = "ws:";
+    else if (u.protocol === "https:")
+      u.protocol = "wss:";
+    if (u.protocol !== "ws:" && u.protocol !== "wss:") {
+      throw new DOMException(`The URL's scheme must be ws or wss, not ${u.protocol.slice(0, -1)}`, "SyntaxError");
+    }
+    if (u.hash)
+      throw new DOMException("The URL contains a fragment", "SyntaxError");
+    const list = typeof protocols === "string" ? [protocols] : [...protocols];
+    if (new Set(list).size !== list.length) {
+      throw new DOMException("The subprotocols contain duplicates", "SyntaxError");
+    }
+    this.url = u.href;
+    this.#id = globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2) + Date.now().toString(36);
+    this.#events = new Channel((e) => this.#receive(e));
+    call("plugin:websocket.Connect", {
+      id: this.#id,
+      url: this.url,
+      protocols: list,
+      headers: [...new Headers(options.headers)]
+    }, this.#events).then(() => this.#finish(1006, "", false, this.#failed ?? "connection lost"), (err) => this.#finish(1006, "", false, this.#failed ?? failure(err)));
+  }
+  get readyState() {
+    return this.#state;
+  }
+  get protocol() {
+    return this.#protocol;
+  }
+  get extensions() {
+    return "";
+  }
+  get bufferedAmount() {
+    return this.#buffered;
+  }
+  get onopen() {
+    return this.#handler("open");
+  }
+  set onopen(fn) {
+    this.#setHandler("open", fn);
+  }
+  get onmessage() {
+    return this.#handler("message");
+  }
+  set onmessage(fn) {
+    this.#setHandler("message", fn);
+  }
+  get onerror() {
+    return this.#handler("error");
+  }
+  set onerror(fn) {
+    this.#setHandler("error", fn);
+  }
+  get onclose() {
+    return this.#handler("close");
+  }
+  set onclose(fn) {
+    this.#setHandler("close", fn);
+  }
+  send(data) {
+    if (this.#state === CONNECTING)
+      throw new DOMException("The connection is not open yet", "InvalidStateError");
+    let size;
+    let message;
+    if (typeof data === "string") {
+      const bytes = encoder.encode(data);
+      size = bytes.length;
+      message = { type: "text", text: data };
+    } else if (typeof Blob !== "undefined" && data instanceof Blob) {
+      size = data.size;
+      message = data.arrayBuffer().then((b) => ({ type: "binary", data: toBase64(new Uint8Array(b)) }), () => ({ type: "skip" }));
+    } else {
+      const bytes = ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
+      size = bytes.length;
+      message = { type: "binary", data: toBase64(bytes) };
+    }
+    this.#buffered += size;
+    if (this.#state !== OPEN)
+      return;
+    const settle = () => this.#buffered -= size;
+    this.#send(message).then(settle, settle);
+  }
+  close(code, reason) {
+    if (code !== undefined && code !== 1000 && !(code >= 3000 && code <= 4999)) {
+      throw new DOMException(`Invalid close code ${code}`, "InvalidAccessError");
+    }
+    const why = reason ?? "";
+    if (encoder.encode(why).length > 123)
+      throw new DOMException("The close reason is over 123 bytes", "SyntaxError");
+    if (this.#state === CLOSING || this.#state === CLOSED)
+      return;
+    if (this.#state === CONNECTING) {
+      this.#state = CLOSING;
+      this.#failed = "closed before the connection was established";
+      this.#events.close();
+      setTimeout(() => this.#finish(1006, "", false, this.#failed));
+      return;
+    }
+    this.#state = CLOSING;
+    this.#send({ type: "close", code: code ?? (why ? 1000 : 1005), reason: why }).catch(() => {});
+  }
+  #send(message) {
+    const seq = ++this.#seq;
+    return Promise.resolve(message).then((m) => call("plugin:websocket.Send", this.#id, seq, m));
+  }
+  #receive(e) {
+    switch (e.type) {
+      case "open":
+        if (this.#state !== CONNECTING)
+          return;
+        this.#state = OPEN;
+        this.#protocol = e.protocol ?? "";
+        this.dispatchEvent(new Event("open"));
+        return;
+      case "text":
+      case "binary": {
+        if (this.#state !== OPEN)
+          return;
+        let data = e.text ?? "";
+        if (e.type === "binary") {
+          const bytes = fromBase64(e.data ?? "");
+          data = this.binaryType === "arraybuffer" ? bytes.buffer : new Blob([bytes]);
+        }
+        this.dispatchEvent(new MessageEvent("message", { data, origin: new URL(this.url).origin }));
+        return;
+      }
+      case "close":
+        this.#finish(e.code ?? 1005, e.reason ?? "", e.clean ?? false, e.error);
+    }
+  }
+  #finish(code, reason, wasClean, error) {
+    if (this.#state === CLOSED)
+      return;
+    this.#state = CLOSED;
+    this.#events.close();
+    if (error) {
+      console.error(`WebSocket connection to '${this.url}' failed: ${error}`);
+      this.dispatchEvent(new Event("error"));
+    }
+    this.dispatchEvent(closeEvent(code, reason, wasClean));
+  }
+  #handler(type) {
+    return this.#handlers.get(type)?.fn ?? null;
+  }
+  #setHandler(type, fn) {
+    let entry = this.#handlers.get(type);
+    if (!entry) {
+      const e = entry = { fn: null };
+      this.#handlers.set(type, e);
+      this.addEventListener(type, (ev) => e.fn?.call(this, ev));
+    }
+    entry.fn = typeof fn === "function" ? fn : null;
+  }
+}
+for (const [name, value] of Object.entries({ CONNECTING, OPEN, CLOSING, CLOSED })) {
+  Object.defineProperty(WebSocket.prototype, name, { value, enumerable: true });
+}
+var src_default = WebSocket;
+function closeEvent(code, reason, wasClean) {
+  if (typeof CloseEvent !== "undefined")
+    return new CloseEvent("close", { code, reason, wasClean });
+  return Object.assign(new Event("close"), { code, reason, wasClean });
+}
+function failure(err) {
+  if (isCallError(err) && err.message.includes("plugin is not used")) {
+    return "the Go side does not use @mygo-plugins/websocket: call mygo.Use(websocket.Plugin) before App.Run";
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+function toBase64(bytes) {
+  const native = bytes.toBase64;
+  if (native)
+    return native.call(bytes);
+  let s = "";
+  for (let i = 0;i < bytes.length; i += 32768) {
+    s += String.fromCharCode.apply(null, bytes.subarray(i, i + 32768));
+  }
+  return btoa(s);
+}
+function fromBase64(s) {
+  const native = Uint8Array.fromBase64;
+  if (native)
+    return native(s);
+  const bin = atob(s);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0;i < bin.length; i++)
+    bytes[i] = bin.charCodeAt(i);
+  return bytes;
+}
+export {
+  WebSocket,
+  src_default as default
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mygo-plugins/websocket",
+  "version": "0.1.8",
+  "description": "A WebSocket whose connections Go makes, for MyGo desktop apps",
+  "keywords": [
+    "mygo",
+    "desktop",
+    "webview",
+    "go",
+    "websocket"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egoist/mygo.git",
+    "directory": "plugins/websocket"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run ../build.ts",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "mygo-runtime": "^0.1.8"
+  },
+  "devDependencies": {
+    "mygo-runtime": "^0.1.8"
+  }
+}