feat(app): R4.3a the page reads the file chunk by chunk and streams it to the worker's sink

Measured at R4.3a (RUST.md §10.5): reading a file inside a WebKit worker costs about
180 MiB of content RSS whatever the method (arrayBuffer, stream, BYOB), 14 MiB on the
page; a page-side BYOB read feeding the worker's FileBytes gives 106 MiB on a 50 MiB file
against 272 in the worker and 76 for the TypeScript. Protocol v1 gains chunk / ack / end:
one 1 MiB buffer travels (transferred) and comes back after each push, so the page holds
one chunk and the worker's sink the only whole copy; no byte is parsed on the page. The
worker refuses an oversize announced before any chunk and a size that changes while
reading. Tests adapted (handler, client with a scripted ack, read failure on the page).
This commit is contained in:
bchanot committed 2026-10-18 18:57:55 +02:00
1 parent 49591c53cd
commit e659924ec0
12 files changed
+552 -272

No files matched your search

+139 -57
View File
@@ -3,20 +3,23 @@ import {
PROTOCOL_VERSION,
type ImportDiag,
type ImportTaskKind,
type WorkerMessage,
} from './protocol'
import { CHUNK_BYTES, chunkSource, type ChunkSource } from './reader'
import { PausableTimer, type Visibility, documentVisibility } from './timers'
/**
* The page side of one import (R4.3, plan §B.1.5 items 1, 3 and 5): creates the worker
* in a try/catch (a `SecurityError` is synchronous), installs the listeners before posting,
* arms the start timer until `ready` then the task timer, settles once on the first of
* `result`, `failed`, an `error` event, a timer, or a cancel, and terminates the worker in
* every case. Everything after the first settlement is ignored.
* arms the start timer until `ready` then the task timer, feeds the file chunk by chunk
* (one travelling buffer, each chunk acknowledged before the next), settles once on the
* first of `result`, `failed`, an `error` event, a read failure, a timer, or a cancel, and
* terminates the worker in every case. Everything after the first settlement is ignored.
*/
/** What `new Worker(…)` gives, narrowed to what the client uses (a test fake fits). */
export interface WorkerLike {
postMessage(message: unknown): void
postMessage(message: unknown, transfer?: Transferable[]): void
terminate(): void
onmessage: ((event: MessageEvent) => void) | null
onerror: ((event: ErrorEvent) => void) | null
@@ -55,6 +58,8 @@ export interface ImportClientOptions {
/** From `ready` to the result (plan §B.3: 20 s hypothesis, set at J1). */
taskTimeoutMs: number
visibility?: Visibility
/** Test seam: the file's chunks. */
source?: (file: File) => ChunkSource
}
export interface ImportRun {
@@ -71,67 +76,144 @@ function reasonOf(phase: 'start' | 'task', kind: string): ImportFailureReason {
return 'engine'
}
export function runImportTask(
input: ImportTaskInput,
options: ImportClientOptions,
): ImportRun {
let worker: WorkerLike | null = null
let timer: PausableTimer | null = null
let ready = false
let done = false
let resolve!: (settlement: ImportSettlement) => void
const settled = new Promise<ImportSettlement>((r) => {
resolve = r
/** One import's moving parts, settled once. */
class ImportClient {
private worker: WorkerLike | null = null
private timer: PausableTimer | null = null
private source: ChunkSource | null = null
private awaitingAck: ((bytes: ArrayBuffer) => void) | null = null
private ready = false
private done = false
private resolve!: (settlement: ImportSettlement) => void
readonly settled = new Promise<ImportSettlement>((resolve) => {
this.resolve = resolve
})
const visibility = options.visibility ?? documentVisibility
const settle = (settlement: ImportSettlement) => {
if (done) return
done = true
timer?.clear()
timer = null
worker?.terminate()
worker = null
resolve(settlement)
constructor(
private readonly input: ImportTaskInput,
private readonly options: ImportClientOptions,
) {}
start(): void {
try {
this.worker = this.options.spawn()
} catch (error) {
this.fail(
'worker_unavailable',
error instanceof Error ? error.name : 'spawn failed',
)
return
}
this.worker.onmessage = (event) => this.onMessage(event.data)
// An `error` event is never masked: it settles the import (and reaches the console).
this.worker.onerror = (event) =>
this.fail(this.ready ? 'crashed' : 'worker_unavailable', event.message)
this.worker.onmessageerror = () =>
this.fail(this.ready ? 'engine' : 'worker_unavailable', 'messageerror')
this.arm(this.options.startTimeoutMs, 'worker_unavailable')
const { task, file, sheet, module } = this.input
this.worker.postMessage({
v: PROTOCOL_VERSION,
type: 'task',
task,
size: file.size,
sheet,
module,
})
}
const fail = (reason: ImportFailureReason, detail: string) =>
settle({ kind: 'failed', reason, detail })
const arm = (ms: number, reason: ImportFailureReason) => {
timer?.clear()
timer = new PausableTimer(
cancel(): void {
this.fail('cancelled', 'cancelled')
}
private onMessage(data: unknown): void {
if (this.done || !isWorkerMessage(data)) return
this.dispatch(data)
}
private dispatch(message: WorkerMessage): void {
switch (message.type) {
case 'ready':
this.ready = true
this.arm(this.options.taskTimeoutMs, 'timeout')
void this.feed()
return
case 'ack':
this.awaitingAck?.(message.bytes)
this.awaitingAck = null
return
case 'result':
this.settle({ kind: 'result', out: message.out, diag: message.diag })
return
case 'failed':
this.fail(reasonOf(message.phase, message.kind), message.detail)
}
}
/** Reads the file chunk by chunk into one buffer the worker hands back after each. */
private async feed(): Promise<void> {
this.source = (this.options.source ?? chunkSource)(this.input.file)
let buffer = new ArrayBuffer(CHUNK_BYTES)
try {
for (;;) {
const chunk = await this.source.next(buffer)
if (this.done) return
if (chunk === null) break
buffer = await this.send(chunk.bytes, chunk.length)
if (this.done) return
}
this.worker?.postMessage({ v: PROTOCOL_VERSION, type: 'end' })
} catch (error) {
this.fail(
'read',
error instanceof Error ? `${error.name}: ${error.message}` : 'read',
)
}
}
/** Posts a chunk (transferred) and resolves with its buffer once acknowledged. */
private send(bytes: ArrayBuffer, length: number): Promise<ArrayBuffer> {
return new Promise((resolve) => {
this.awaitingAck = resolve
this.worker?.postMessage(
{ v: PROTOCOL_VERSION, type: 'chunk', bytes, length },
[bytes],
)
})
}
private arm(ms: number, reason: ImportFailureReason): void {
this.timer?.clear()
const visibility = this.options.visibility ?? documentVisibility
this.timer = new PausableTimer(
ms,
() => fail(reason, `${reason} after ${ms} ms`),
() => this.fail(reason, `${reason} after ${ms} ms`),
visibility,
)
}
try {
worker = options.spawn()
} catch (error) {
fail(
'worker_unavailable',
error instanceof Error ? error.name : 'spawn failed',
)
return { settled, cancel: () => fail('cancelled', 'cancelled') }
private fail(reason: ImportFailureReason, detail: string): void {
this.settle({ kind: 'failed', reason, detail })
}
worker.onmessage = (event) => {
const data: unknown = event.data
if (!isWorkerMessage(data)) return
if (data.type === 'ready') {
ready = true
arm(options.taskTimeoutMs, 'timeout')
} else if (data.type === 'result') {
settle({ kind: 'result', out: data.out, diag: data.diag })
} else {
fail(reasonOf(data.phase, data.kind), data.detail)
}
private settle(settlement: ImportSettlement): void {
if (this.done) return
this.done = true
this.timer?.clear()
this.timer = null
this.worker?.terminate()
this.worker = null
void this.source?.cancel()
this.source = null
this.resolve(settlement)
}
// An `error` event is never masked: it settles the import (and reaches the console).
worker.onerror = (event) =>
fail(ready ? 'crashed' : 'worker_unavailable', event.message)
worker.onmessageerror = () =>
fail(ready ? 'engine' : 'worker_unavailable', 'messageerror')
arm(options.startTimeoutMs, 'worker_unavailable')
worker.postMessage({ v: PROTOCOL_VERSION, type: 'task', ...input })
return { settled, cancel: () => fail('cancelled', 'cancelled') }
}
export function runImportTask(
input: ImportTaskInput,
options: ImportClientOptions,
): ImportRun {
const client = new ImportClient(input, options)
client.start()
return { settled: client.settled, cancel: () => client.cancel() }
}
+108 -86
View File
@@ -3,8 +3,9 @@ import { closedRefusal } from '@faunosteo/core-wasm'
import {
describeError,
failureKindOf,
isPageMessage,
PROTOCOL_VERSION,
type ImportTaskKind,
type ChunkMessage,
type ImportTaskMessage,
type WorkerFailurePhase,
type WorkerMessage,
@@ -13,9 +14,9 @@ import {
/**
* The import worker's logic (R4.3, plan §B.1.5 items 2 and 4), apart from the worker
* global so that vitest runs it in-process on the Node module: the engine is injected.
* One task per worker: instantiate, answer `ready`, build the sheet handle, stream the
* file into the module's memory (the file lives once, never as an ArrayBuffer here), run
* the core, answer `result`; every throwable becomes one `failed` with its phase and kind.
* One task per worker: instantiate, answer `ready`, build the sheet handle, sink the
* chunks the page reads (one copy, in the module's memory), run the core on `end`, answer
* `result`; every throwable becomes one `failed` with its phase and kind.
*/
/** What the glue gives once instantiated. */
@@ -30,10 +31,12 @@ export type EngineLoader = (
module: WebAssembly.Module | null,
) => Promise<WorkerEngine>
/** The caps the worker checks before reading a byte (the core enforces the same). */
/** The caps the worker checks before reserving a byte (the core enforces the same). */
export const MAX_PDF_BYTES = 50 * 1024 * 1024
export const MAX_COPY_BYTES = 16 * 1024 * 1024
export type Post = (message: WorkerMessage, transfer?: Transferable[]) => void
/** The core's failure envelope, for the caps the worker applies itself. */
function refusal(kind: string, detail: string): string {
return JSON.stringify({ ok: false, kind, detail })
@@ -52,99 +55,118 @@ function sheetHandle(engine: WorkerEngine, sheet: string): GlueSheetHandle {
}
}
interface Gathered {
bytes: GlueFileBytes
chunks: number
}
/** One task's state, from the task message to its settlement. */
class ImportTask {
private engine: WorkerEngine | null = null
private handle: GlueSheetHandle | null = null
private sink: GlueFileBytes | null = null
private chunks = 0
private settled = false
private readonly started = performance.now()
/** Streams the file into the module's memory, one chunk live at a time. */
async function gather(
engine: WorkerEngine,
file: File,
): Promise<Gathered | null> {
const bytes = new engine.FileBytes(file.size)
const reader = file.stream().getReader()
let chunks = 0
for (;;) {
const { done, value } = await reader.read()
if (done) return { bytes, chunks }
chunks += 1
// A push refused means the file is not the size it announced: not a Faunosteo file.
if (!bytes.push(value)) {
await reader.cancel()
bytes.free()
return null
constructor(
private readonly task: ImportTaskMessage,
private readonly load: EngineLoader,
private readonly post: Post,
) {}
/** Instantiates, answers `ready`, reserves the sink; a cap refusal settles at once. */
async start(): Promise<void> {
let phase: WorkerFailurePhase = 'start'
try {
this.engine = await this.load(this.task.module)
this.post({ v: PROTOCOL_VERSION, type: 'ready' })
phase = 'task'
this.handle = sheetHandle(this.engine, this.task.sheet)
const cap = this.task.task === 'pdf' ? MAX_PDF_BYTES : MAX_COPY_BYTES
if (this.task.size > cap) {
this.result(refusal(this.kind(), 'over the size cap'))
return
}
this.sink = new this.engine.FileBytes(this.task.size)
} catch (error) {
this.fail(phase, error)
}
}
}
/** The task's outcome envelope text and the chunk count. */
async function runTask(
engine: WorkerEngine,
handle: GlueSheetHandle,
task: ImportTaskKind,
file: File,
): Promise<{ out: string; chunks: number }> {
const cap = task === 'pdf' ? MAX_PDF_BYTES : MAX_COPY_BYTES
const kind = task === 'pdf' ? 'invalid_pdf' : 'invalid'
if (file.size > cap)
return { out: refusal(kind, 'over the size cap'), chunks: 0 }
const gathered = await gather(engine, file)
if (!gathered)
return { out: refusal(kind, 'size changed while reading'), chunks: 0 }
const out =
task === 'pdf'
? handle.import_pdf_bytes(gathered.bytes)
: handle.restore_copy_bytes(gathered.bytes)
return { out, chunks: gathered.chunks }
}
/** Sinks one chunk and hands its buffer back; a refused push means the size changed. */
chunk(message: ChunkMessage): void {
if (this.settled || !this.sink) return
const view = new Uint8Array(message.bytes, 0, message.length)
if (!this.sink.push(view)) {
this.sink.free()
this.sink = null
this.result(refusal(this.kind(), 'size changed while reading'))
return
}
this.chunks += 1
this.post({ v: PROTOCOL_VERSION, type: 'ack', bytes: message.bytes }, [
message.bytes,
])
}
/**
* The handler of the task message: `load` instantiates the module (the posted one, or
* fetched), `post` sends the answers. Resolves once the task has settled either way.
*/
export function createWorkerHandler(
load: EngineLoader,
post: (message: WorkerMessage) => void,
): (data: unknown) => Promise<void> {
const fail = (phase: WorkerFailurePhase, error: unknown) =>
post({
/** Runs the core on the gathered bytes. */
end(): void {
if (this.settled || !this.sink || !this.handle) return
try {
const sink = this.sink
this.sink = null
const out =
this.task.task === 'pdf'
? this.handle.import_pdf_bytes(sink)
: this.handle.restore_copy_bytes(sink)
this.result(out)
} catch (error) {
this.fail('task', error)
}
}
private kind(): string {
return this.task.task === 'pdf' ? 'invalid_pdf' : 'invalid'
}
private result(out: string): void {
this.settled = true
const linearBytes = this.engine?.memory?.buffer.byteLength ?? null
const diag = {
ms: performance.now() - this.started,
linearBytes,
chunks: this.chunks,
}
this.post({ v: PROTOCOL_VERSION, type: 'result', out, diag })
}
private fail(phase: WorkerFailurePhase, error: unknown): void {
this.settled = true
this.post({
v: PROTOCOL_VERSION,
type: 'failed',
phase,
kind: failureKindOf(error),
detail: describeError(error),
})
return async (data) => {
if (!isTaskMessage(data)) return
let phase: WorkerFailurePhase = 'start'
try {
const engine = await load(data.module)
post({ v: PROTOCOL_VERSION, type: 'ready' })
phase = 'task'
const started = performance.now()
const handle = sheetHandle(engine, data.sheet)
const { out, chunks } = await runTask(
engine,
handle,
data.task,
data.file,
)
const linearBytes = engine.memory?.buffer.byteLength ?? null
const diag = { ms: performance.now() - started, linearBytes, chunks }
post({ v: PROTOCOL_VERSION, type: 'result', out, diag })
} catch (error) {
fail(phase, error)
}
}
}
function isTaskMessage(data: unknown): data is ImportTaskMessage {
if (typeof data !== 'object' || data === null) return false
const record = data as { v?: unknown; type?: unknown; task?: unknown }
return (
record.v === PROTOCOL_VERSION &&
record.type === 'task' &&
(record.task === 'pdf' || record.task === 'copy')
)
/**
* The handler of the page's messages: `load` instantiates the module (the posted one, or
* fetched), `post` sends the answers. Messages outside the protocol are ignored.
*/
export function createWorkerHandler(
load: EngineLoader,
post: Post,
): (data: unknown) => Promise<void> {
let task: ImportTask | null = null
return async (data) => {
if (!isPageMessage(data)) return
if (data.type === 'task') {
if (task) return
task = new ImportTask(data, load, post)
await task.start()
} else if (data.type === 'chunk') {
task?.chunk(data)
} else {
task?.end()
}
}
}
+2 -2
View File
@@ -27,8 +27,8 @@ const loadEngine = async (
return { SheetHandle, FileBytes, memory: exports.memory ?? null }
}
const handle = createWorkerHandler(loadEngine, (message) =>
scope.postMessage(message),
const handle = createWorkerHandler(loadEngine, (message, transfer = []) =>
scope.postMessage(message, transfer),
)
scope.onmessage = (event: MessageEvent<unknown>) => {
+50 -9
View File
@@ -1,7 +1,8 @@
/**
* Messages between the page and the import worker (R4.3, plan §B.1.5), tagged `v: 1`.
* The page posts one task; the worker answers `ready` once its instance runs, then one
* `result` or one `failed`. Anything after the first settlement is ignored by the page.
* The page posts one task, then the file chunk by chunk, then `end`; the worker answers
* `ready` once its instance runs, `ack` per chunk, then one `result` or one `failed`.
* Anything after the first settlement is ignored by the page.
*/
export const PROTOCOL_VERSION = 1
@@ -12,19 +13,47 @@ export interface ImportTaskMessage {
v: typeof PROTOCOL_VERSION
type: 'task'
task: ImportTaskKind
/** The picked file, never read on the page's thread. */
file: File
/** The picked file's size: the worker reserves it and refuses more. */
size: number
/** The bundled sheet payload text the page's runtime builds its handle from. */
sheet: string
/** The compiled module of the page's runtime when it holds one; else the worker fetches. */
module: WebAssembly.Module | null
}
/**
* One chunk of the file, read on the page's thread into a buffer the worker hands back
* with `ack` (both transferred, never copied): the page holds one chunk at a time, the
* worker's sink the only whole copy. Measured at R4.3a: reading a file inside a WebKit
* worker costs about 180 MiB whatever the method; read on the page and streamed, 106.
*/
export interface ChunkMessage {
v: typeof PROTOCOL_VERSION
type: 'chunk'
bytes: ArrayBuffer
length: number
}
/** The page read the whole file: the worker runs the core. */
export interface EndMessage {
v: typeof PROTOCOL_VERSION
type: 'end'
}
export type PageMessage = ImportTaskMessage | ChunkMessage | EndMessage
export interface WorkerReadyMessage {
v: typeof PROTOCOL_VERSION
type: 'ready'
}
/** The chunk is in the sink; its buffer comes back for the next read. */
export interface WorkerAckMessage {
v: typeof PROTOCOL_VERSION
type: 'ack'
bytes: ArrayBuffer
}
export interface WorkerResultMessage {
v: typeof PROTOCOL_VERSION
type: 'result'
@@ -60,21 +89,33 @@ export interface WorkerFailedMessage {
export type WorkerMessage =
| WorkerReadyMessage
| WorkerAckMessage
| WorkerResultMessage
| WorkerFailedMessage
/** True for a message of this protocol, from a worker of the same build. */
export function isWorkerMessage(data: unknown): data is WorkerMessage {
const WORKER_TYPES = new Set(['ready', 'ack', 'result', 'failed'])
const PAGE_TYPES = new Set(['task', 'chunk', 'end'])
function ofProtocol(data: unknown, types: Set<string>): boolean {
if (typeof data !== 'object' || data === null) return false
const record = data as { v?: unknown; type?: unknown }
return (
record.v === PROTOCOL_VERSION &&
(record.type === 'ready' ||
record.type === 'result' ||
record.type === 'failed')
typeof record.type === 'string' &&
types.has(record.type)
)
}
/** True for a message of this protocol, from a worker of the same build. */
export function isWorkerMessage(data: unknown): data is WorkerMessage {
return ofProtocol(data, WORKER_TYPES)
}
/** True for a message of this protocol, from the page. */
export function isPageMessage(data: unknown): data is PageMessage {
return ofProtocol(data, PAGE_TYPES)
}
/** Error name and first message line, bounded, for a `failed` message. */
export function describeError(error: unknown): string {
const name = error instanceof Error ? error.name : 'Error'
+60
View File
@@ -0,0 +1,60 @@
/**
* The page's read of the picked file, one chunk at a time into a buffer that travels to
* the worker and back (R4.3a measurement: a file read inside a WebKit worker costs about
* 180 MiB whatever the method; read here, 106, and 14 on the page alone). A BYOB reader
* fills the buffer the worker handed back; without BYOB support (happy-dom), the default
* reader's chunks are copied into it. Nothing here parses a byte.
*/
export const CHUNK_BYTES = 1024 * 1024
export interface ChunkSource {
/** The next chunk's length in `buffer`, or null at the end; `buffer` is consumed. */
next(
buffer: ArrayBuffer,
): Promise<{ bytes: ArrayBuffer; length: number } | null>
cancel(): Promise<void>
}
type ByobReader = ReadableStreamBYOBReader
type DefaultReader = ReadableStreamDefaultReader<Uint8Array>
function byobSource(reader: ByobReader): ChunkSource {
return {
async next(buffer) {
const { done, value } = await reader.read(new Uint8Array(buffer))
if (done || !value) return null
return { bytes: value.buffer as ArrayBuffer, length: value.byteLength }
},
cancel: () => reader.cancel().catch(() => undefined),
}
}
/** The default reader's chunks copied into the travelling buffer, split when longer. */
function defaultSource(reader: DefaultReader): ChunkSource {
let pending: Uint8Array | null = null
return {
async next(buffer) {
if (!pending || pending.byteLength === 0) {
const { done, value } = await reader.read()
if (done || !value) return null
pending = value
}
const length = Math.min(pending.byteLength, buffer.byteLength)
new Uint8Array(buffer, 0, length).set(pending.subarray(0, length))
pending = pending.subarray(length)
return { bytes: buffer, length }
},
cancel: () => reader.cancel().catch(() => undefined),
}
}
/** A chunk source over `file`, BYOB when the engine offers it. */
export function chunkSource(file: File): ChunkSource {
const stream = file.stream()
try {
return byobSource(stream.getReader({ mode: 'byob' }))
} catch {
return defaultSource(stream.getReader())
}
}