Extensions and primitives

Modules l3i::extension, l3i::packed, l3i::sequence, l3i::quat, l3i::raster, l3i::udp and, with the soft-render feature, l3i::soft_render. Extensions, Primitives and Built-in extensions are the guides.

The planner#

Module l3i::extension: describe once, resolve per runtime, instantiate after planning. An Extension declares what it provides in describe, callables included, without touching a VM. RuntimePlanBuilder::finalize orders extensions by their dependency graph (deterministically), merges owners with augmenters into one type per key, assigns tags (pinned, then Required, then Preferred while tags last), allocates the compiler’s 32 userdata type slots the same way, assigns atoms densely, lays out direct slots, resolves memory categories, checks services and capabilities, and validates every name the definitions or the VM would choke on. Runtime::from_plan then builds a VM, registers the merged types, wires the planned direct members to one set of generic callbacks, opens the declared modules, runs every install in order, freezes modules, registers them for require, derives compiler metadata for compat globals, and publishes. A plan is immutable and instantiates any number of runtimes; each gets its own tags, atoms and direct plan.

use std::cell::Cell;
use l3i::extension::{Extension, ExtensionDescriptor, InstallContext, RuntimePlan, RuntimePolicy};
use l3i::source::CompileConstant;
use l3i::userdata::{Owned, Userdata};
use l3i::{Result, Runtime};

struct Counter { value: Cell<i64> }

unsafe impl Userdata for Counter {
    const NAME: &'static str = "dream.tests.Counter";
}

struct Core;

impl Extension for Core {
    fn id(&self) -> &'static str { "dream.core" }

    fn describe(&self, d: &mut ExtensionDescriptor) -> Result<()> {
        let mut counter = d.userdata::<Counter>("dream.tests.Counter");
        counter.doc("A counter.");
        counter.method("get", |c: &Counter| c.value.get()).signature("(self): number");
        counter.method("add", |c: &Counter, n: i64| c.value.set(c.value.get() + n)).untyped();
        counter
            .property("twice", |c: &Counter| c.value.get() * 2, |c: &Counter, v: i64| c.value.set(v / 2))
            .signature("number");
        counter.metamethod("__tostring", |c: &Counter| format!("Counter({})", c.value.get()));
        d.module("@dream/core")
            .doc("Counters.")
            .function("new", |n: i64| Owned(Counter { value: Cell::new(n) }))
            .signature("(n: number) -> dream_tests_Counter")
            .constant("ANSWER", CompileConstant::Number(42.0));
        d.memory_category("dream.core");
        Ok(())
    }

    fn install(&self, cx: &mut InstallContext<'_>) -> Result<()> {
        let _category = cx.memory_category("dream.core")?;
        Ok(())
    }
}

fn main() -> Result<()> {
    let plan = RuntimePlan::builder().policy(RuntimePolicy::new()).extension(Core).finalize()?;
    let runtime = Runtime::from_plan(&plan)?;
    runtime.exec("local core = require('@dream/core') local c = core.new(5) c:add(2) assert(c:get() == 7) assert(c.twice == 14)")?;
    Ok(())
}

ExtensionDescriptor#

Everything one extension declares in describe. Debug.

UserdataBuilder and MemberDecl#

The typed view of a UserdataDecl under construction: declares a member and binds its callable in one call. Callables are Clone because a plan instantiates any number of runtimes and binds each member once per VM; whatever a callable captures is shared by every one of those runtimes. Mutable per-runtime state belongs in InstallContext::insert_state.

One declared member. fn signature(&mut self, signature: impl Into<String>) -> &mut Self sets the Luau signature or type for definition output ((self, x: number): integer for a method, a type for a getter, setter or field); fn untyped(&mut self) -> &mut Self leaves it without a type on purpose (the definitions say ...any); fn doc(&mut self, doc: impl Into<String>) -> &mut Self. A member with neither a signature nor untyped fails the plan: types are never accidental. Clone, Debug.

Method is reachable by __namecall and, on a tagged type, the direct namecall path; Getter and Setter through bound accessors; Field through a direct primitive getter, which needs a tag. Clone, Copy, Debug, Eq, Hash.

How much a type wants a Luau tag: planning fails without one; take one when free and fall back to the canonical untagged metatable otherwise; never tag. Default Preferred. Clone, Copy, Debug, Eq.

Whether a type takes one of the compiler’s userdata type slots. Luau’s compiler and code generator tell at most 32 userdata types apart per VM; a type whose methods lower natively needs one (and a tag), and a plan that cannot give a Required type its slot does not finalize rather than leave that path interpreted. Default Preferred.

A userdata type one extension owns or augments. Clone, Debug.

What a sequence or stream view is, for the generated definitions.

A host service an extension needs, matched by Rust type. Clone, Debug.

ModuleDecl#

A native module the extension provides, required by its path (an optional leading @, then ASCII letters, digits, /, ., _, -). Clone, Debug.

The member just declared. fn signature(self, signature: impl Into<String>) -> Self, fn doc(self, doc: impl Into<String>) -> Self, fn untyped(self) -> Self, fn module(self) -> &'m mut ModuleDecl, and function, constant, installed to continue the chain.

The vocabulary for signatures follows the runtime, where Luau’s checker keeps integer and number apart: a packed value, a Bits64 or an Integer result is integer; a count, a size or an f64 is number; a class is its generated name, the key with dots replaced (dream_udp_Client); a module type is Module__dream_archive_ba2.

RuntimePolicy#

Execution policy for runtimes made from a plan: the VM’s configuration and what scripts may do. native_code exists with the jit feature. Clone, Debug, Default.

Builder methods, each self -> Self: new(), capability(name), compat_global(module_path, global), sandbox(enabled), standard_libraries(enabled), limits(limits), profiler(enabled), first_tag(tag), debug_root(root), native_code(policy); and fn grants(&self, capability: &str) -> bool.

Feature jit: native code settings a plan reuses for every runtime it creates. hooks are the host’s lowering hooks, asked after the defaults and before the extensions’ own. Clone, Debug, Default.

RuntimePlanBuilder and RuntimePlan#

Collects extensions, services and policy. Default.

Finalize errors (Error::Logic, or Error::Permission for a missing capability): an extension registered twice or claiming the reserved dream.udp id; two ids folding to one debug prefix; a missing or cyclic requires; a module provided twice, a member declared twice, a compat global for a path nothing provides; a type owned twice, a Rust type under two keys, two types sharing a Userdata::NAME or a generated class name; an augmentation of a type its extension does not require; a member with neither a signature nor untyped(); a key, path, member or global spelled in a way Luau or the definitions would refuse; no tag left for a Required type, a pinned tag on a Never type, direct fields on a Never type; no compiler slot for a Required type; more than 4096 atoms or slots; more than 255 memory categories; a missing service; two types on one packed kind.

An immutable, reusable description of one runtime composition. Debug.

A type after ownership and augmentations merged: tag is what this plan assigned or None for the canonical untagged metatable; bytecode_type is TAGGED_USERDATA_BASE + slot when the plan gave it a compiler slot. fn member(&self, name: &str) -> Option<&ResolvedMember> and fn has_direct_slots(&self) -> bool. Clone, Debug.

A member with its VM-local resolution. Every method, getter and setter of a tagged type has a slot; a direct field has none unless through_slot: its name is also a method, getter or setter elsewhere in the plan, and since Luau rewrites every obj.name whose key has an atom into the direct-access opcode, such a field is served through a slot like a getter rather than failing the plan. fn access_kind(&self) -> AccessKind. Clone, Debug.

A module after planning; global is the compatibility global the policy exposes it as. Clone, Debug.

InstallContext and ModuleInstaller#

The install-phase view of the runtime one extension receives.

One module table under construction: the declared functions and constants first, then what the provider’s install adds, then frozen by the planner.

A name the plan did not declare with installed, a declared function or constant, or a member set twice is a logic error.

Packed values#

Module l3i::packed: fixed-size byte layouts for buffers and semantic 64-bit scalars.

A value with a fixed little-endian byte layout inside a Luau buffer. Implemented for the Rust integers, f32, f64, Vector3 (12 bytes), Packed<T> (8 bytes), Color (4 bytes) and Color16 (8 bytes). BufferView::read_packed and write_packed cross the boundary with one bounds check and one copy, so read_from never sees a slice of Luau’s storage.

A semantic value that lives in one Luau integer: a 4-bit kind, 4 flag bits, a 56-bit payload. The kind is checked on every read, so untyped script code handing the wrong integer to a native operation fails with a type error instead of decoding garbage. Kinds are a registry: 1..=4 are l3i’s own and fixed for good (a packed integer is a file and wire format), 5..=15 are the application’s, declared per extension with ExtensionDescriptor::packed or per runtime with Runtime::register_packed. A Packed<T> crossing a VM where T is not the kind’s registered owner is a logic error.

One registered kind. fn of<T: PackedScalar>() -> PackedKind and fn is_builtin(&self) -> bool. Clone, Copy, Debug, Eq.

l3i’s own kinds in kind order from 1.

The Luau integer carrying a packed scalar of kind T. FromView (an integer of kind T::KIND, after the registry check), Push, Param, Return, BufferPack, SequenceItem. Clone, Copy, Debug, Eq, Hash.

The bit pattern for kind, flags and payload, refusing a kind outside 1..=15, flags above four bits or a payload above 56 bits rather than truncating; and the split back into (kind, flags, payload).

Sequences and streams#

Module l3i::sequence. A Sequence wraps a Rust collection and shows it to scripts as #items, items[i] (1-based, nil past the end), for item in items do and items:toTable(); only the item a script touches is pushed. A Stream is the cursor-backed variant for results that cannot be indexed: for item in stream do opens a private cursor per loop, nothing else. Both are ordinary userdata types declared through the planner (ExtensionDescriptor::sequence, stream) or configured by hand.

A random-access native collection. NAME is the userdata __type, a debug name such as dream.archive.Entries; get is 0-based.

A collection consumed through a per-loop cursor with interior mutability inside.

The userdata payloads; both implement Userdata with NAME = S::NAME. Each has fn push<'s>(scope: &'s impl Scope, source: S) -> Result<ValueView<'s>> (the type must be registered in this VM).

An element pushed by value: every Push scalar, Value, Table, Function, Packed<T>, Option<T: SequenceItem>, and Owned<T> for any registered T, which moves the row into a fresh userdata without needing Clone.

One step of a view’s iterator as a Return: the next control value and the element.

Configure a metatable whose __type is S::NAME by hand: toTable, __len, __iter and an integer __index over the methods table (call after any extra methods); or __iter opening one cursor per loop. Indexing reads the receiver and the key straight from Luau’s value layout; an exact integer key selects an element, a fractional or out-of-range number is nil, never a rounded neighbour.

dream.quat#

Module l3i::quat: rotations as packed Luau integers. A unit quaternion is compressed smallest-three into the 56-bit payload: two bits name the largest component, the other three are 18-bit lanes over [-1/√2, 1/√2], and the omitted one is rebuilt from the unit norm. The identity and axis-aligned rotations round-trip exactly; a random rotation comes back within 1.6e-5 rad. The packed form is storage and transport, never the live accumulator: keep long-lived rotation state as Quat on the host.

Extension dream.quat, module @dream/quat: IDENTITY (a folded constant), axisAngle(axis, angle), fromXYZW(x, y, z, w), toXYZW(q), mul(a, b), inverse(q), slerp(a, b, t), rotate(q, v), angleTo(a, b), key(q, flags), keyRotation(k), keyFlags(k). axisAngle and fromXYZW refuse a zero or non-finite input, slerp a non-finite weight, and key takes the low four bits of an exact integer. With jit, math() returns a dream.quat.Math receiver (class dream_quat_Math) whose rotate, mul, slerp, fromXYZW, key, keyRotation and keyFlags lower to IR when the script annotates it.

A unit quaternion in f64: the reference representation and the host’s accumulator. Mul is the Hamilton product a * b (apply b, then a).

A rotation packed into 56 bits. fn encode(q: Quat) -> PackedRotation normalises first only when q is not already unit; fn decode(self) -> Quat.

The packed scalar kind of a rotation (kind 1, flags always zero). fn pack(q: Quat) -> Packed<Quaternion>.

Kind 2: a rotation plus four opaque flag bits (higher bits are dropped when packing). fn pack(rotation: Quat, flags: u8) -> Packed<AnimationKey>.

Module l3i::quat::lowering (feature jit): struct Math, the payload-free tagged receiver; struct Lowering, the NativeCodeHooks set the extension registers; fn lowered_sites() -> usize, a diagnostic for tests; and the interpreter oracles fn rotate(q: Packed<Quaternion>, v: Vector3) -> Vector3, fn mul(a: Packed<Quaternion>, b: Packed<Quaternion>) -> Packed<Quaternion> and fn slerp(a: Packed<Quaternion>, b: Packed<Quaternion>, t: f64) -> Result<Packed<Quaternion>>. Only single-result, fixed-arity call sites lower: bind a nested call’s result to a local first.

dream.raster#

Module l3i::raster: raster scalars as packed integers.

The module: the folded constants TRANSPARENT, BLACK, WHITE, CLIP_ALL, CLIP_MAX_COORD, TRANSPARENT16, BLACK16, WHITE16; the strict constructors rgba8(r, g, b, a) and rgb8(r, g, b) (an integer outside 0..=255 is an error); channels, packed, withAlpha, lerp, mul, add, scale, premultiply, clip, clipBounds; and math(), a dream.raster.Math receiver whose methods (rgba8, rgb8, red, green, blue, alpha, channels, withAlpha, lerp, mul, add, scale, premultiply, each also in a 16 form, plus widen and narrow) clamp their inputs and lower to native code under jit when annotated (local C: dream_raster_Math = raster.math()). Shader semantics: inputs clamp, results round to nearest, NaN gives channel 0.

An RGBA8 color, kind 3. Its 32-bit form, red in bits 0..7 through alpha in bits 24..31, is exactly the four bytes [r, g, b, a] a vertex color or a texel holds; every u32 is a color. Channel meaning (straight or premultiplied) belongs to the consumer. BufferPack as four bytes.

The wide form for formats that require 16 bits per channel: red in bits 0..15 through alpha in bits 48..63, the little-endian u64 being an RGBA16 pixel. It fills the whole Luau integer and so has no kind nibble: any integer is accepted as a Color16, and nothing at runtime tells it from an RGBA8 color or an id. The same methods as Color over u16, plus const WIDEN: f64 = 257.0, const fn bits(self) -> i64, fn widen(color: Color) -> Color16 (x * 257) and fn narrow(self) -> Color (round(x / 257)). FromView, Push, Param, Return, BufferPack.

An integer pixel rectangle, kind 4: four 14-bit fields, so a coordinate is at most MAX_COORD (16383). A deliberate limit of the packed form, not of a renderer: a surface past 16K on an axis needs a clip type of its own.

The color arithmetic receiver (dream.raster.Math). Module l3i::raster::lowering (feature jit): struct ColorMath, the hook set, and fn lowered_sites() -> usize.

dream.udp#

Module l3i::udp: the dream-net bridge, extension dream.udp, module @dream/udp, types dream.udp.Server, dream.udp.Client and dream.udp.Schema. Every RuntimePlan carries it and the id is reserved. Peer, event, channel and client ids are Luau integers; sizes and counters plain numbers; payloads Luau buffers (or strings on send), copied on the way in and out so no Lua memory is retained by the transport; the transport clock is the plan’s; the server private key never reaches Luau; nothing calls into Luau from inside dream-net.

A monotonic clock the transport reads on update(), seconds as f64; one counting from its creation.

The extension, added by the planner. fn new() -> Self (a monotonic clock started now), fn with_clock(clock: Clock) -> Self, Default. The module declares schema(options) (a strict option table: version, maxMessagesPerPacket?, channels, events), the constants CONNECT_TOKEN_BYTES, MAX_EVENT_PAYLOAD, MAX_CHANNELS, and the installed client{ schema, bind? }, which raises Error::Permission unless the policy grants network.transport.

dream.udp.Schema, untagged: getters version, fingerprint, eventCount, channelCount; methods eventId(name), channelId(name), eventName(id), channelName(id).

dream.udp.Server: a dream-net server as scripts see it. Created by the host in Rust, which keeps the private key. Scripts get update(), pollInto(buffer) returning kind, peer, a, b, c with one payload copy and no allocation, sendEvent(peer, eventId, bytes, offset?, length?), flush(), and the per-peer statistics methods.

dream.udp.Client, with fn new(client: Client, clock: Clock) -> UdpClient, fn push<'s>(scope: &'s impl Scope, client: Client, clock: Clock) -> Result<ValueView<'s>> and fn with(&self, body: impl FnOnce(&mut Client)). Connection statistics are direct fields on the client.

Delivery names as scripts spell them.

dream.soft_render#

Module l3i::soft_render, feature soft-render: dream-soft-render’s CPU rasterizer as a small software rendering device. Rectangles, textured rectangles and triangle meshes from Luau buffers are drawn immediately in call order into a renderer-owned RGBA8 surface. Colors are raster integers the renderer reads as premultiplied; clip rectangles are ClipRect integers; vertex data is a buffer of 20-byte vertices and an index buffer of u32, borrowed for one draw call and never kept. Malformed input is an error in the renderer’s own words, never a quietly clipped draw.

Requires dream.raster in the same plan. The module: renderer(), vertices(), premultiply(color), and the folded constants MAX_SURFACE_PIXELS, MAX_TEXTURE_BYTES, VERTEX_BYTES.

dream.soft_render.Renderer: one surface and a texture store. Scripts get beginFrame(width, height), createTexture(width, height, pixels), readInto(buffer, offset?) and the direct fields width and height. fn new() -> Renderer (Default); fn with<R>(&self, body: impl FnOnce(&mut SoftwareRenderer) -> R) -> Result<R> runs body on the underlying renderer for host code and fails if a script call on this renderer is in progress.

dream.soft_render.Frame, from beginFrame: clear(color), rect(min, max, color, clip), image(min, max, uvMin, uvMax, texture, tint, clip), mesh(vertexBuffer, indexBuffer, texture?, clip), finish(). A token for one frame, stale after finish() or the next beginFrame.

dream.soft_render.Texture: update(...) and free(); storage is freed on free() or when collected.

dream.soft_render.Vertices, from vertices(): write(buffer, offset, pos, uv, color) packs a vertex with one bounds check and returns the next offset. With jit the call lowers to native stores.

The interpreter path of Vertices:write, and the oracle its lowering must match. The offset truncates toward zero like the buffer library’s; anything outside the buffer is buffer access out of bounds.

Module l3i::soft_render::lowering (feature jit): struct VertexWriter, the hook set, and fn lowered_sites() -> usize.

dream.bytes#

Module l3i::bytes, feature bytes; the module functions, the receiver and the codecs are described from the script’s side in Built-in extensions.

The extension; id() is "dream.bytes", the module path is MODULE ("@dream/bytes"). Clone, Copy, Debug, Default.

The receiver behind bytes.math() (Userdata::NAME "dream.bytes.Math"), tagged and given a compiler type slot, both Required.

Lower-case hex, the module’s toHex.

In l3i::convert: the return type for bytes a script receives as a new buffer. Pushing allocates the buffer at the vector’s length and copies once; returning a Vec<u8> pushes a string instead. Push and a single Return.

dream.data#

Module l3i::data, feature data; the Luau side is in Built-in extensions. The types are usable from Rust without a VM; the bound functions are the semantic oracle for the native lowering.

The extension; id() is EXTENSION_ID ("dream.data"), the module path MODULE ("@dream/data"), and LOWERING_GLOBAL ("__l3i_data") the global alias the install publishes for the dialect’s recognized pipelines. Clone, Copy, Debug, Default.

An element representation, named as the buffer library names its reads. parse(what, name) accepts a script’s spelling or raises an argument error naming every one; name(), size(). KINDS is all eight in receiver order. Match with a wildcard arm: a kind can be added.

A kind with the distance between consecutive elements and the field’s position inside a record: "f32" is contiguous, "f32@16" the first f32 of every 16-byte record, "f32@16+12" the field twelve bytes in. new(kind, stride, offset), contiguous(kind), parse(what, name). A stride below the element size is an error; one above it skips the rest of the record.

A comparison as a script names it ("eq" … "ge"); parse(what, name). Exhaustive: the set is closed.

The userdata behind data.compare and data.selection (Userdata::NAME "dream.data.Selection"): a bitset over the positions of a span of one length, #[repr(C)] so native code reads its length word and words pointer at fixed offsets. new(len), len(), is_empty(), count(), get(index).

The typed receivers, dream_data_Kind_u8 through dream_data_Kind_f64 (Userdata::NAME "dream.data.Kind.u8" and so on), tagged and given a compiler type slot, both Preferred: KIND, new(stride), layout(). The element kind is the type parameter; the stride is a run-time property of the value.

A reduction over every element or over those a comparison with the threshold accepts: the receivers’ members. Reduction::new(op, filter), Reduction::MEMBERS (all thirty-nine), op.member_name(filter) ("sumGt"), op.name(), comparison.suffix().

dream.intern#

Module l3i::intern, feature intern; the Luau side is in Built-in extensions.

The extension; id() is "dream.intern", the module path is MODULE ("@dream/intern"). Clone, Copy, Debug, Default.

When two byte sequences are one identity. parse("exact" | "ascii-nocase"), name().

The pool without Luau, for hosts that intern from Rust. new(policy), intern(&[u8]) -> Result<u32> (the token, added on first sight; an error only past 2^32 - 1 identities or 4 GiB of text), find(&[u8]) -> Option<u32>, resolve(i64) -> Option<&[u8]> (the first spelling), len(), is_empty(), policy(), memory() (native bytes held).

The userdata behind intern.new (Userdata::NAME "dream.intern.Pool", tagged and given a compiler type slot, both Required): an Interner shared with the functions Pool:interner() binds, which keep it alive, laid out #[repr(C)] for native code.

dream.intl#

Module l3i::intl, feature intl; the Luau side is in Built-in extensions. Every type works from Rust without a VM. The enums Grouping, FormatterError, Operand, NumberError and LocaleError and the structs DecimalOptions and UnsupportedLocale are #[non_exhaustive]: match them with a wildcard arm and build them with their constructors. PluralKind and Category are closed sets and stay exhaustive.

The extension; id() is "dream.intl", the module path is MODULE ("@dream/intl"). Clone, Copy, Debug, Default.

A BCP 47 tag, validated and spelled canonically; also the userdata behind intl.locale ("dream.intl.Locale"). parse(&str) -> Result<Locale, LocaleError>, as_str() (the canonical tag), base_name(), language(), script(), region(), variants(). Equality and hashing are the canonical tag’s. Display, FromStr. canonicalize(&str) -> Result<String, LocaleError> and with_canonical(&str, f), which hands the spelling to f without allocating for a tag of up to 64 bytes without extensions, need no Locale. LocaleError is Empty or Invalid { input, reason }.

A number to select a category for or format. decimal() is the exact fixed_decimal::Decimal; a Decimal string keeps its visible fraction digits, a Number reads as its shortest round-trip decimal. Also a binding parameter (number | integer | string). NumberError is NotFinite(f64), Malformed(String) or TooLong(String).

One locale’s rules; also the userdata behind intl.pluralRules ("dream.intl.PluralRules"). new(&Locale, PluralKind) -> Result<PluralRules, UnsupportedLocale>, category(Operand) -> Result<Category, NumberError>, categories(), locale(), kind(). PluralKind is Cardinal or Ordinal; Category is Zero, One, Two, Few, Many or Other, with name() the CLDR keyword.

One locale’s decimal format under DecimalOptions::new().grouping(..).fraction_digits(min, max) (Grouping is Auto, Never or Min2; the digit counts are Option<u8>, at most MAX_FRACTION_DIGITS, 100). new(&Locale, DecimalOptions) -> Result<DecimalFormatter, FormatterError>, format_to(Operand, &mut String) -> Result<(), NumberError>, format(Operand), locale(), grouping(), min_fraction_digits(), max_fraction_digits() (resolved). FormatterError is FractionDigitsOutOfRange, FractionDigitsInverted or Unsupported(UnsupportedLocale). The Luau handle, "dream.intl.DecimalFormatter", wraps one with the buffer format writes into.

IrBuilder::namecall_call(pcpos) emits the namecall and call Luau would have emitted for the pair at pcpos: a userdata namecall hook that lowers a fast path keeps the bound method as its slow path with it, without a VM exit, since returning true skips both instructions.

dream.luau#

Module l3i::syntax, feature syntax; the Luau side is in Built-in extensions.

The extension; id() is "dream.luau" (EXTENSION_ID), the module path is MODULE ("@dream/luau"). Clone, Copy, Debug, Default.

dream.tcp#

Module l3i::tcp, feature tcp; the Luau side is in Built-in extensions.

The extension; id() is "dream.tcp" (EXTENSION_ID), the module path is MODULE ("@dream/tcp"). new() (also Default), max_pollers(u32) (pollers open per runtime, 1 to 4096, default 64: a poller needs no capability and holds OS descriptors the VM’s memory limit does not see). Clone, Copy, Debug.

The userdata behind tcp.listen ("dream.tcp.Listener"). from_std(std::net::TcpListener, max_streams: u32) -> io::Result<Listener> wraps a listener the host bound and makes it nonblocking; push(scope, listener) hands it to a script, which needs no capability to use it. local_address(), is_closed(), close().

The userdata behind tcp.connect and Listener:accept ("dream.tcp.Stream"). from_std(std::net::TcpStream) -> io::Result<Stream> wraps a connected stream the host made; push(scope, stream). state() -> StreamState (Connecting, Connected, Failed, Closed, with name() the script’s spelling; #[non_exhaustive], so match with a wildcard arm), peer_address(), local_address(), close().

The userdata behind tcp.poller ("dream.tcp.Poller"); close() releases every watch and the OS poller. Listeners, streams and pollers are !Send: they belong to the runtime that made them.

dream.dns#

Module l3i::dns, feature dns; the Luau side is in Built-in extensions.

new(Resolver), max_requests(u32) (open requests per runtime, default 64), max_lookups(u32) (a runtime’s lookups occupying the resolver, queued or running, default 8), Default over Resolver::system(). id() is "dream.dns"; RESOLVE_CAPABILITY is "network.dns.resolve"; MAX_TIMEOUT_MS 60000, MAX_ADDRESSES 64.

A bounded pool of lookup threads, cheap to clone and shareable between runtimes. new(ResolverConfig::new(workers, queue), Arc<dyn Lookup>) (clamped to 1..=64 and 1..=4096), system() (the process’s default over SystemLookup), config(), load() (queued lookups, threads started). Dropping the last handle ends the workers as they finish. ResolverConfig has public workers and queue fields and is #[non_exhaustive], so it is built with new, never with a struct literal.

fn lookup(&self, host: &str, port: u16) -> Result<Vec<SocketAddr>, LookupError>, run only on the resolver’s threads; SystemLookup is the OS’s. LookupError is NotFound, TemporaryFailure or Other(String), with kind() the script’s spelling; #[non_exhaustive].

The userdata behind dns.resolve ("dream.dns.Request"): status(), cancel(), close().

l3i::hostname::normalize(&str) -> Result<Name, String> (features dns or tls) is the mapping both modules use; Name { original, ascii, literal }, bare() without the trailing dot.

dream.tls#

Module l3i::tls, feature tls; the Luau side is in Built-in extensions.

id() is "dream.tls"; it requires dream.tcp and widens dream_tcp_Watchable with dream_tls_Stream. new() (also Default), max_configs(u32) (client and server configurations alive per runtime, 1 to 4096, default 32: a configuration needs no capability and holds native memory the VM’s memory limit does not see). Clone, Copy, Debug.

The userdata behind tls.client and tls.server ("dream.tls.Stream"): state() -> TlsState (Handshaking, Open, Failed, Closed, with name(); #[non_exhaustive]), close(). ClientConfig and ServerConfig are the configuration userdata ("dream.tls.ClientConfig", "dream.tls.ServerConfig").