@solidrt/flux-types 0.0.25 → 0.0.27

package/README.md

@@ -46,7 +46,8 @@ rely on must be named.
 
 - `Flux` global (`version`, `capabilities`).
 - `flux:*` modules: `flux:http`, `flux:fs`, `flux:sqlite`, `flux:subprocess`,
-  `flux:p2p`, `flux:process`, `flux:path`, and (on a gui-enabled runtime)
+  `flux:p2p`, `flux:net`, `flux:mdns`, `flux:process`, `flux:path`, `flux:wasm`, `flux:ffi`,
+  and (on a gui-enabled runtime)
   `flux:camera`, `flux:microphone`, `flux:audio`, `flux:gpu`.
 - Web-standard globals: `console`, `fetch` + `Headers`/`Request`/`Response`,
   `setTimeout`/`setInterval`/`queueMicrotask`, `performance`, `WebSocket`,

package/gui/gpu.d.ts

@@ -36,6 +36,65 @@ declare module "flux:gpu" {
   ): number
   /** Update a shader texture's float uniforms by name and re-render it. */
   export function setShaderParams(id: number, params: Record<string, number>): void
+
+  export type Topology = "points" | "lines" | "line-strip" | "triangles" | "triangle-strip"
+  /**
+   * One float attribute of an interleaved vertex. The attribute list's order
+   * defines the byte layout; locations are resolved by name against the
+   * vertex shader's `in` declarations.
+   */
+  export type VertexAttribute = { name: string; format: "f32" | "vec2" | "vec3" | "vec4" }
+
+  /**
+   * Compile a GLSL ES vertex+fragment pipeline into an offscreen texture of
+   * the given size and render it once. Sources without a `#version` line get
+   * a 300 es preamble declaring `iResolution`/`iTime` (no vUV: varyings are
+   * the pipeline's own). `attributes` describes one interleaved vertex in
+   * `buffer` (a {@link createBuffer} id); omit both for attributeless
+   * rendering via gl_VertexID. `vertexCount` defaults to the whole buffer
+   * (buffer size / vertex stride). With `depth: true` the pipeline gets a
+   * private depth buffer, cleared and tested on every render. The target is
+   * cleared to `clearColor` (default transparent black) before each draw.
+   * Returns a texture id: display it with `<texture src>`, drive uniforms via
+   * the `params` prop or {@link setShaderParams}, destroy with
+   * {@link destroyTexture}.
+   */
+  export function createPipeline(
+    vertexSrc: string,
+    fragmentSrc: string,
+    width: number,
+    height: number,
+    opts?: {
+      params?: Record<string, number>
+      textures?: Record<string, number>
+      attributes?: VertexAttribute[]
+      buffer?: number
+      topology?: Topology
+      vertexCount?: number
+      depth?: boolean
+      clearColor?: [number, number, number, number]
+    },
+  ): number
+
+  /**
+   * Create a vertex buffer from raw bytes (interleave attribute data to match
+   * the pipeline's attribute list). Buffer ids are their own space, separate
+   * from texture ids.
+   */
+  export function createBuffer(data: Uint8Array): number
+  /**
+   * Overwrite part of a vertex buffer at `byteOffset` (default 0), within the
+   * size it was created with. Pipelines drawing from the buffer re-render
+   * with their last-applied params.
+   */
+  export function writeBuffer(id: number, data: Uint8Array, byteOffset?: number): void
+  /** Destroy a vertex buffer. Destroy pipelines drawing from it first. */
+  export function destroyBuffer(id: number): void
+  /**
+   * Set how many vertices a pipeline texture draws and re-render it, e.g.
+   * after writing a variable amount of dynamic geometry into its buffer.
+   */
+  export function setDrawCount(id: number, count: number): void
   /**
    * Capture a render-tree node's subtree into a new GPU texture, resolving once
    * it has been rendered on the next paint pass. The node must be attached to

package/index.d.ts

@@ -7,6 +7,8 @@
 /// <reference path="./modules/p2p.d.ts" />
 /// <reference path="./modules/net.d.ts" />
 /// <reference path="./modules/mdns.d.ts" />
+/// <reference path="./modules/wasm.d.ts" />
+/// <reference path="./modules/ffi.d.ts" />
 
 // Web-standard globals. The runtime is QuickJS, not a browser or Node, so it
 // ships no lib.dom / @types/bun: these declarations are the sole source for

package/modules/ffi.d.ts

@@ -0,0 +1,63 @@
+declare module "flux:ffi" {
+  /**
+   * A scalar ffi value. i32/f32/f64 marshal as number; i64 and ptr marshal as
+   * BigInt (an address or i64 does not fit a JS number without precision
+   * loss). A number is also accepted where an i64 or ptr is expected.
+   */
+  type FfiValue = number | bigint
+  type FfiTypeName = "i32" | "i64" | "f32" | "f64" | "ptr"
+
+  /** One symbol declaration. `returns` defaults to "void". */
+  type SymbolDecl = {
+    args: FfiTypeName[]
+    returns?: FfiTypeName | "void"
+  }
+
+  /** The symbols to resolve at load time, keyed by exported name. */
+  type Symbols = Record<string, SymbolDecl>
+
+  /**
+   * A JS function backing a minted C function pointer. Called synchronously
+   * while a `symbols.*` call is on the stack; its return value is coerced to
+   * the callback's declared result type ("void" ignores it). A throw cannot
+   * abort the native frame: the callback returns zeroes, the native call runs
+   * to completion, and the exception is rethrown after it returns.
+   */
+  type CallbackFunction = (...args: FfiValue[]) => FfiValue | void
+
+  /**
+   * A native shared library. The native counterpart of `flux:wasm`'s Module:
+   * declare what you need up front, every declared symbol must resolve.
+   *
+   * There is NO sandbox: the library runs with full process rights, loading
+   * runs its constructors, and a declared signature that does not match the
+   * real ABI is undefined behavior. Only load trusted code.
+   */
+  export class Library {
+    /**
+     * Load a shared library from bytes (e.g. a bundled binary import; written
+     * to a temp file behind the scenes) or a filesystem path, and resolve
+     * every declared symbol. A missing symbol throws.
+     */
+    constructor(source: Uint8Array | ArrayBuffer | string, symbols: Symbols)
+    /**
+     * The declared symbols as bound JS functions, keyed by name. Destructure
+     * once and reuse: the object is rebuilt on each access.
+     */
+    readonly symbols: Record<string, (...args: FfiValue[]) => FfiValue | undefined>
+    /**
+     * Mint a C function pointer (returned as a BigInt address) that invokes
+     * `func` when the library calls it during a `symbols.*` call. Callbacks
+     * may only fire while such a call is on the stack, on the same thread;
+     * the pointer stays valid for the lifetime of the library.
+     */
+    callback(func: CallbackFunction, decl: SymbolDecl): bigint
+    /**
+     * Copy `len` bytes out of process memory at `ptr`. No bounds checking is
+     * possible: a bad pointer is undefined behavior.
+     */
+    readMemory(ptr: FfiValue, len: number): Uint8Array
+    /** Copy `bytes` into process memory at `ptr`. Same caveat as readMemory. */
+    writeMemory(ptr: FfiValue, bytes: Uint8Array | ArrayBuffer): void
+  }
+}

package/modules/fs.d.ts

@@ -22,8 +22,16 @@ declare module "flux:fs" {
     exists(): Promise<boolean>
     /** Resolve to the file's metadata (size, type, mtime). */
     stat(): Promise<FileStat>
+    /**
+     * Read exactly `length` bytes starting at byte `offset`. A range extending
+     * past end-of-file rejects rather than short-reading; clamp against
+     * `stat()` size first.
+     */
+    read(offset: number, length: number): Promise<Uint8Array>
     /** Write `data`, replacing any existing contents. */
     write(data: string | Uint8Array): Promise<void>
+    /** Append `data` to the end of the file, creating it if missing. */
+    append(data: string | Uint8Array): Promise<void>
   }
 
   type FluxDir = {

package/modules/http.d.ts

@@ -1,4 +1,6 @@
 declare module "flux:http" {
+  import type { Endpoint } from "flux:p2p"
+
   /** Path parameters captured from a route pattern (e.g. ":page"). */
   type RouteParams = Record<string, string>
 
@@ -93,6 +95,11 @@ declare module "flux:http" {
     close(code?: number, reason?: string): void
     /** Connection state: CONNECTING 0, OPEN 1, CLOSING 2, CLOSED 3. */
     readonly readyState: number
+    /**
+     * The peer's IP address (or, for a connection accepted over the `p2p`
+     * option, the peer's endpoint id), or undefined when unknown.
+     */
+    readonly remoteAddress: string | undefined
   }
 
   /**
@@ -129,6 +136,18 @@ declare module "flux:http" {
     headers?: Record<string, string> | Headers
   }
 
+  /**
+   * A peer address, as returned by {@link Server.requestIP}. A p2p peer has no
+   * IP: `address` is its endpoint id, `port` is 0, and `family` is `"p2p"`.
+   */
+  type SocketAddress = {
+    /** The peer's IP address, or a p2p peer's endpoint id. */
+    address: string
+    /** The peer's port (0 for a p2p peer). */
+    port: number
+    family: "IPv4" | "IPv6" | "p2p"
+  }
+
   type Server = {
     /** The bound port. */
     readonly port: number
@@ -151,6 +170,11 @@ declare module "flux:http" {
     publish(topic: string, data: string | Uint8Array): number
     /** How many sockets are currently subscribed to `topic`. */
     subscriberCount(topic: string): number
+    /**
+     * The peer address of the connection `req` arrived on, or null when unknown
+     * (e.g. a JS-constructed Request).
+     */
+    requestIP(req: Request): SocketAddress | null
     /**
      * Stop accepting new connections and gracefully shut down open ones. Safe to
      * call more than once.
@@ -158,6 +182,14 @@ declare module "flux:http" {
     stop(): void
   }
 
+  /** Options for accepting `flux:p2p` connections alongside the TCP listener. */
+  type P2pOptions = {
+    /** The `flux:p2p` Endpoint to accept connections on. */
+    endpoint: Endpoint
+    /** ALPN protocol matched against each incoming connection. */
+    protocol: string
+  }
+
   type ServeOptions = {
     /** Port to listen on. */
     port: number
@@ -184,6 +216,13 @@ declare module "flux:http" {
      * without it `upgrade()` always returns false.
      */
     websocket?: WebSocketHandlers
+    /**
+     * Accept connections on a `flux:p2p` Endpoint alongside the TCP listener:
+     * each incoming connection whose ALPN matches `protocol` has the HTTP/WS
+     * protocol spoken over its first bidirectional stream. `server.stop()`
+     * stops accepting; the endpoint itself stays open for its owner.
+     */
+    p2p?: P2pOptions
   }
 
   /**

package/modules/p2p.d.ts

@@ -10,6 +10,19 @@ declare module "flux:p2p" {
     relayUrl?: string
     /** Protocols this endpoint will {@link Endpoint.accept}. */
     protocols?: string[]
+    /**
+     * Bind local-only: no relay and no address publishing/lookup, so nothing
+     * about the endpoint leaves the machine except the ticket itself, whose
+     * direct IPs same-network peers dial. Excludes `relayUrl`; a bare-id
+     * `connect` cannot resolve a local endpoint (tickets only).
+     */
+    local?: boolean
+    /**
+     * Pin the UDP bind port (IPv4-only). With a persisted `secretKey` this keeps
+     * the whole ticket stable across restarts, so a paired client can re-dial
+     * the old ticket. Omit for an ephemeral port.
+     */
+    port?: number
   }
 
   /** One transport address from {@link Endpoint.connInfo}. */
@@ -54,7 +67,7 @@ declare module "flux:p2p" {
     /**
      * Bind an endpoint.
      *
-     * @param opts  secretKey, relayUrl, protocols.
+     * @param opts  secretKey, relayUrl, protocols, local, port.
      */
     static create(opts?: EndpointOptions): Promise<Endpoint>
     /** This endpoint's dial address: the string peers pass to {@link connect}. */

package/modules/wasm.d.ts

@@ -0,0 +1,87 @@
+declare module "flux:wasm" {
+  /**
+   * A scalar wasm value. i32/f32/f64 marshal as number; i64 marshals as BigInt
+   * (an i64 does not fit a JS number without precision loss). A number is also
+   * accepted where an i64 is expected.
+   */
+  type WasmValue = number | bigint
+  type WasmTypeName = "i32" | "i64" | "f32" | "f64"
+
+  /** A function import a module requires, `{ module, name }`-keyed like the standard. */
+  type ImportInfo = {
+    module: string
+    name: string
+    params: WasmTypeName[]
+    results: WasmTypeName[]
+  }
+
+  /**
+   * An instance export. `params`/`results` are present only for functions with
+   * all-scalar signatures.
+   */
+  type ExportInfo =
+    | { name: string; kind: "function"; params: WasmTypeName[]; results: WasmTypeName[] }
+    | { name: string; kind: "memory" | "other" }
+
+  /**
+   * A host function backing a guest import. Called synchronously during an
+   * export call; must return values matching the import's declared results:
+   * nothing for zero results, a single value for one, an array for several.
+   * A throw aborts the wasm call and propagates. May re-enter the instance
+   * (e.g. via {@link Instance.callIndirect}).
+   */
+  type HostFunction = (...args: WasmValue[]) => WasmValue | WasmValue[] | void
+
+  /** Host functions keyed by import module then name, e.g. `{ env: { mul } }`. */
+  type Imports = Record<string, Record<string, HostFunction>>
+
+  export class Module {
+    /**
+     * Parse and validate a wasm binary (wat text bytes are also accepted).
+     * Throws on invalid input or on an unsupported import (non-function, or
+     * non-scalar signature).
+     */
+    constructor(bytes: Uint8Array | ArrayBuffer)
+    /**
+     * The function imports this module requires, in the order the host
+     * functions are indexed.
+     */
+    readonly imports: ImportInfo[]
+    /**
+     * Instantiate with host functions. Every listed import must resolve to a
+     * function; a missing or non-function entry throws.
+     */
+    instantiate(imports: Imports): Instance
+  }
+
+  /** An instantiated module. Created with {@link Module.instantiate}. */
+  export class Instance {
+    /** The module's exports. */
+    readonly exports: ExportInfo[]
+    /**
+     * Call an exported function. Arguments are coerced to the export's declared
+     * parameter types. Returns `undefined` for no results, the single value for
+     * one, or an array for several. Host imports hit during the call dispatch
+     * to the functions passed to `instantiate`; a throw from one aborts the
+     * call.
+     */
+    call(name: string, ...args: WasmValue[]): WasmValue | WasmValue[] | undefined
+    /**
+     * Call a function by its index in the module's exported function table:
+     * `table[index](...args)`. This is how a host function invokes a guest
+     * function pointer it received as an integer (e.g. a C callback). Same
+     * coercion and host-import dispatch rules as {@link call}; safe to use
+     * from within a host function (re-entrant).
+     */
+    callIndirect(index: number, ...args: WasmValue[]): WasmValue | WasmValue[] | undefined
+    /**
+     * The exported memory's current size in bytes, or `undefined` if the
+     * module exports no memory.
+     */
+    readonly memorySize: number | undefined
+    /** Copy `len` bytes out of the exported memory at `ptr`. */
+    readMemory(ptr: number, len: number): Uint8Array
+    /** Copy `bytes` into the exported memory at `ptr`. */
+    writeMemory(ptr: number, bytes: Uint8Array | ArrayBuffer): void
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "license": "MIT",
   "author": "Antoine van Wel",
   "types": "index.d.ts",

package/standards/fetch.d.ts

@@ -25,6 +25,12 @@ interface Headers {
   delete(name: string): void
   /** Add a value for `name` without replacing existing ones. */
   append(name: string, value: string): void
+  /**
+   * Call `callback(value, name, headers)` for each entry. Iterates entries as
+   * stored (insertion order, duplicates separate); WHATWG iterates sorted with
+   * duplicate names combined.
+   */
+  forEach(callback: (value: string, name: string, headers: Headers) => void, thisArg?: any): void
 }
 
 declare let Headers: {