feat(app): R4.3b/c import worker, client, controller; HomeRoute on the disposable worker
Protocol v1 (task → ready → result | failed with phase and kind), the worker entry with the glue bundled statically and the page's compiled Module posted, the file streamed into the module's memory; client with start and task timers (paused while hidden), settle-once, terminate always, error events never masked; module-level controller (one import at a time, cancel on leaving Home, worker chunk prefetched once the engine is loaded); the settlement mapped to the B.1.8 messages (OD-5: a trap, a timeout or an unreadable file is « Erreur de lecture du PDF. », never a corrupt PDF). HomeRoute keeps its routing and size pre-checks, loads its own index after acceptance, drops a result when the session changed. Tests: handler and client in-process, the corpus message test (O8 51, O7 stored inputs, O2/O3/Step 5), the six existing suites migrated to the real worker logic.
This commit is contained in:
1 parent
52471dbbc0
commit
6d1cce6e06
26 files changed
+2164
-247
No files matched your search
@@ -1,5 +1,5 @@
|
||||
import { useNavigate } from 'react-router-dom'
|
||||
import { useRef, useState } from 'react'
|
||||
import { useEffect, useRef, useState } from 'react'
|
||||
import type {
|
||||
ArchiveReadOutcome,
|
||||
RebaseOutcome,
|
||||
@@ -10,21 +10,23 @@ import { CoreStoppedBanner } from '@/components/report/CoreStoppedNotice'
|
||||
import ReplaceSessionDialog from '@/components/report/ReplaceSessionDialog'
|
||||
import Button from '@/components/ui/Button'
|
||||
import Card from '@/components/ui/Card'
|
||||
import {
|
||||
importAttachment,
|
||||
ImportError,
|
||||
MAX_ATTACHMENT_BYTES,
|
||||
MAX_PDF_BYTES,
|
||||
readAttachment,
|
||||
readRescueCopy,
|
||||
} from '@/pdf/import'
|
||||
import { coreRuntime, coreStopped } from '@/core/runtime'
|
||||
import type { ImportSettlement } from '@/core/worker/client'
|
||||
import { cancelImport, startImport } from '@/core/worker/controller'
|
||||
import { MAX_COPY_BYTES, MAX_PDF_BYTES } from '@/core/worker/handler'
|
||||
import { copyRestoreOf, ImportError, pdfImportOf } from '@/core/worker/outcome'
|
||||
import type { ImportTaskKind } from '@/core/worker/protocol'
|
||||
import {
|
||||
isSessionInProgress,
|
||||
useReportStore,
|
||||
type ImportedSession,
|
||||
} from '@/state/reportStore'
|
||||
import type { SheetIndex } from '@/services/sheetIndex'
|
||||
import { loadSheetIndex, useSheetAvailability } from '@/sheets/useSheet'
|
||||
import {
|
||||
loadSheetBundleText,
|
||||
loadSheetIndex,
|
||||
useSheetAvailability,
|
||||
} from '@/sheets/useSheet'
|
||||
import { DEFAULT_SPECIES_ID } from './NewReportRoute'
|
||||
import { useT } from '@/i18n/useT'
|
||||
import { coreFailureMessage } from '@/core/failure'
|
||||
@@ -119,6 +121,8 @@ function importErrorMessage(err: unknown, t: Translate): string {
|
||||
return t('home.import.error_invalid_copy')
|
||||
case 'core_unavailable':
|
||||
return coreFailureMessage(t, 'home.import.error_core_unavailable')
|
||||
case 'generic':
|
||||
return t('home.import.error_generic')
|
||||
}
|
||||
}
|
||||
|
||||
@@ -143,20 +147,39 @@ function firstContentByte(head: Uint8Array): number | undefined {
|
||||
* is JSON (an object) or is named as such; anything else goes the PDF path and its error.
|
||||
*/
|
||||
function isRescueCopy(file: File, head: Uint8Array): boolean {
|
||||
const start = new TextDecoder('latin1').decode(head.slice(0, PDF_MAGIC.length))
|
||||
const start = new TextDecoder('latin1').decode(
|
||||
head.slice(0, PDF_MAGIC.length),
|
||||
)
|
||||
if (start === PDF_MAGIC) return false
|
||||
if (firstContentByte(head) === 0x7b) return true
|
||||
return file.name.toLowerCase().endsWith('.json') || file.type === 'application/json'
|
||||
return (
|
||||
file.name.toLowerCase().endsWith('.json') ||
|
||||
file.type === 'application/json'
|
||||
)
|
||||
}
|
||||
|
||||
/** The copy's text, refused (never altered) when it is over the cap or not valid UTF-8. */
|
||||
async function readCopyText(file: File): Promise<string> {
|
||||
if (file.size > MAX_ATTACHMENT_BYTES) throw new ImportError('invalid_copy')
|
||||
try {
|
||||
return new TextDecoder('utf-8', { fatal: true }).decode(await file.arrayBuffer())
|
||||
} catch {
|
||||
throw new ImportError('invalid_copy')
|
||||
/**
|
||||
* One task in the disposable import worker (R4.3, plan §B.1.5): the page refuses up front
|
||||
* when its own engine stopped, hands the file (never read here), the sheet payload and
|
||||
* its compiled module to the worker, and reads the settlement. Diagnostics in DEV only.
|
||||
*/
|
||||
async function runImportTask(
|
||||
task: ImportTaskKind,
|
||||
file: File,
|
||||
): Promise<ImportSettlement> {
|
||||
if (coreStopped()) throw new ImportError('core_unavailable')
|
||||
const sheet = await loadSheetBundleText(DEFAULT_SPECIES_ID)
|
||||
if (!sheet) throw new ImportError('core_unavailable')
|
||||
const module = await (
|
||||
coreRuntime().compiledModule() ?? Promise.resolve(null)
|
||||
).catch(() => null)
|
||||
const settlement = await startImport({ task, file, sheet, module })
|
||||
// Diagnostics only (never the outcome: it holds the bilan's names), DEV console only.
|
||||
if (import.meta.env.DEV) {
|
||||
const diag = settlement.kind === 'result' ? settlement.diag : settlement
|
||||
console.debug('[import]', task, diag)
|
||||
}
|
||||
return settlement
|
||||
}
|
||||
|
||||
export default function HomeRoute() {
|
||||
@@ -169,48 +192,64 @@ export default function HomeRoute() {
|
||||
const [busy, setBusy] = useState(false)
|
||||
const [confirmingReplace, setConfirmingReplace] = useState(false)
|
||||
const t = useT()
|
||||
// Leaving Home cancels a running import: its worker is terminated, its result dropped.
|
||||
useEffect(() => cancelImport, [])
|
||||
|
||||
/** A Faunosteo PDF: its attachment, read and rebased by the core on the loaded sheet. */
|
||||
async function readPdf(file: File): Promise<ImportRead> {
|
||||
// The engine refuses the same size; checking first keeps a huge file out of memory.
|
||||
if (file.size > MAX_PDF_BYTES) throw new ImportError('invalid_pdf')
|
||||
const bytes = new Uint8Array(await file.arrayBuffer())
|
||||
const attachment = await readAttachment(bytes)
|
||||
/** The page's own index, loaded after the worker accepted the file, for `hydrateImport`. */
|
||||
async function mainIndex(): Promise<SheetIndex> {
|
||||
const index = await loadSheetIndex(DEFAULT_SPECIES_ID)
|
||||
if (!index) throw new ImportError('core_unavailable')
|
||||
const { read: outcome, rebase } = importAttachment(attachment, index)
|
||||
return index
|
||||
}
|
||||
|
||||
/** A Faunosteo PDF: its attachment, read and rebased by the worker's core on the sheet. */
|
||||
async function readPdf(file: File): Promise<ImportRead> {
|
||||
// The worker and the core refuse the same size; checking first reads nothing.
|
||||
if (file.size > MAX_PDF_BYTES) throw new ImportError('invalid_pdf')
|
||||
const { read: outcome, rebase } = pdfImportOf(
|
||||
await runImportTask('pdf', file),
|
||||
)
|
||||
return {
|
||||
session: { report: rebase.report, archive: outcome.archive },
|
||||
index,
|
||||
index: await mainIndex(),
|
||||
lines: importMessages(outcome, rebase, t),
|
||||
}
|
||||
}
|
||||
|
||||
/** A rescue copy: read before any session change, so a refusal leaves the tab untouched. */
|
||||
async function readCopy(file: File): Promise<ImportRead> {
|
||||
const text = await readCopyText(file)
|
||||
const index = await loadSheetIndex(DEFAULT_SPECIES_ID)
|
||||
if (!index) throw new ImportError('core_unavailable')
|
||||
const rebase = readRescueCopy(text, index)
|
||||
if (file.size > MAX_COPY_BYTES) throw new ImportError('invalid_copy')
|
||||
const { rebase } = copyRestoreOf(await runImportTask('copy', file))
|
||||
const count = String(rebase.unresolvedZones + rebase.unresolvedFindings)
|
||||
return {
|
||||
session: { report: rebase.report, archive: null },
|
||||
index,
|
||||
lines: rebase.rebased ? [t('editor.draft_rebased').replace('{count}', count)] : [],
|
||||
index: await mainIndex(),
|
||||
lines: rebase.rebased
|
||||
? [t('editor.draft_rebased').replace('{count}', count)]
|
||||
: [],
|
||||
}
|
||||
}
|
||||
|
||||
/** Read, rebase onto the loaded sheet, open; the editor always works on that sheet. */
|
||||
async function importFile(file: File) {
|
||||
const head = new Uint8Array(await file.slice(0, SNIFF_BYTES).arrayBuffer())
|
||||
const read = isRescueCopy(file, head) ? await readCopy(file) : await readPdf(file)
|
||||
const reportAtPick = useReportStore.getState().report
|
||||
const read = isRescueCopy(file, head)
|
||||
? await readCopy(file)
|
||||
: await readPdf(file)
|
||||
// The session changed under the import (another tab action): its result is dropped.
|
||||
if (useReportStore.getState().report !== reportAtPick) return
|
||||
const opened = hydrateImport(read.session, read.index)
|
||||
// A tab text that could not be set aside would be overwritten: resolve it first.
|
||||
if (!opened.ok) {
|
||||
// A core failure reading the tab's draft is an engine error, not a held text.
|
||||
if (opened.reason !== 'held') throw new ImportError('core_unavailable')
|
||||
window.alert(
|
||||
t(opened.engine ? 'session.held_blocked_engine' : 'session.held_blocked'),
|
||||
t(
|
||||
opened.engine
|
||||
? 'session.held_blocked_engine'
|
||||
: 'session.held_blocked',
|
||||
),
|
||||
)
|
||||
navigate('/editor')
|
||||
return
|
||||
|
||||
@@ -0,0 +1,137 @@
|
||||
import {
|
||||
isWorkerMessage,
|
||||
PROTOCOL_VERSION,
|
||||
type ImportDiag,
|
||||
type ImportTaskKind,
|
||||
} from './protocol'
|
||||
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.
|
||||
*/
|
||||
|
||||
/** What `new Worker(…)` gives, narrowed to what the client uses (a test fake fits). */
|
||||
export interface WorkerLike {
|
||||
postMessage(message: unknown): void
|
||||
terminate(): void
|
||||
onmessage: ((event: MessageEvent) => void) | null
|
||||
onerror: ((event: ErrorEvent) => void) | null
|
||||
onmessageerror: ((event: MessageEvent) => void) | null
|
||||
}
|
||||
|
||||
export interface ImportTaskInput {
|
||||
task: ImportTaskKind
|
||||
file: File
|
||||
sheet: string
|
||||
module: WebAssembly.Module | null
|
||||
}
|
||||
|
||||
/**
|
||||
* `worker_unavailable`: the worker could not be created, failed before `ready`, or did not
|
||||
* answer `ready` in time; `crashed`: a trap or an `error` event during the task;
|
||||
* `timeout`: the task timer; `read`: the file could not be read; `engine`: the module
|
||||
* refused the sheet or failed otherwise during the task; `cancelled`: the page gave up.
|
||||
*/
|
||||
export type ImportFailureReason =
|
||||
| 'worker_unavailable'
|
||||
| 'crashed'
|
||||
| 'timeout'
|
||||
| 'read'
|
||||
| 'engine'
|
||||
| 'cancelled'
|
||||
|
||||
export type ImportSettlement =
|
||||
| { kind: 'result'; out: string; diag: ImportDiag }
|
||||
| { kind: 'failed'; reason: ImportFailureReason; detail: string }
|
||||
|
||||
export interface ImportClientOptions {
|
||||
spawn: () => WorkerLike
|
||||
/** Until `ready`: the module's fetch, compile and instantiation. */
|
||||
startTimeoutMs: number
|
||||
/** From `ready` to the result (plan §B.3: 20 s hypothesis, set at J1). */
|
||||
taskTimeoutMs: number
|
||||
visibility?: Visibility
|
||||
}
|
||||
|
||||
export interface ImportRun {
|
||||
settled: Promise<ImportSettlement>
|
||||
/** Terminates the worker and settles `cancelled` unless already settled. */
|
||||
cancel(): void
|
||||
}
|
||||
|
||||
/** The failure reason of a `failed` message, per §B.1.8. */
|
||||
function reasonOf(phase: 'start' | 'task', kind: string): ImportFailureReason {
|
||||
if (phase === 'start') return 'worker_unavailable'
|
||||
if (kind === 'trap') return 'crashed'
|
||||
if (kind === 'read') return 'read'
|
||||
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
|
||||
})
|
||||
const visibility = options.visibility ?? documentVisibility
|
||||
|
||||
const settle = (settlement: ImportSettlement) => {
|
||||
if (done) return
|
||||
done = true
|
||||
timer?.clear()
|
||||
timer = null
|
||||
worker?.terminate()
|
||||
worker = null
|
||||
resolve(settlement)
|
||||
}
|
||||
const fail = (reason: ImportFailureReason, detail: string) =>
|
||||
settle({ kind: 'failed', reason, detail })
|
||||
const arm = (ms: number, reason: ImportFailureReason) => {
|
||||
timer?.clear()
|
||||
timer = new PausableTimer(
|
||||
ms,
|
||||
() => 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') }
|
||||
}
|
||||
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)
|
||||
}
|
||||
}
|
||||
// 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') }
|
||||
}
|
||||
@@ -0,0 +1,72 @@
|
||||
import workerUrl from './import.worker?worker&url'
|
||||
import {
|
||||
runImportTask,
|
||||
type ImportRun,
|
||||
type ImportSettlement,
|
||||
type ImportTaskInput,
|
||||
} from './client'
|
||||
import type { WorkerLike } from './client'
|
||||
|
||||
/**
|
||||
* One import at a time for the page (R4.3, plan §B.1.5 items 6 and 7): a new start
|
||||
* cancels the running one, leaving Home cancels it, and the worker script is prefetched
|
||||
* once the editor has loaded the engine so that a later offline import can start.
|
||||
*/
|
||||
|
||||
/** Until `ready`: a cold fetch, compile and instantiation on a slow device. */
|
||||
export const IMPORT_START_TIMEOUT_MS = 10_000
|
||||
/** From `ready` to the result (plan §B.3: 20 s hypothesis, confirmed or moved at J1). */
|
||||
export const IMPORT_TIMEOUT_MS = 20_000
|
||||
|
||||
type Spawn = () => WorkerLike
|
||||
|
||||
const spawnWorker: Spawn = () =>
|
||||
new Worker(workerUrl, { type: 'module', name: 'faunosteo-import' })
|
||||
|
||||
let spawn: Spawn = spawnWorker
|
||||
let running: ImportRun | null = null
|
||||
let prefetched = false
|
||||
|
||||
/** Starts an import; a running one is cancelled first (its result dropped). */
|
||||
export function startImport(input: ImportTaskInput): Promise<ImportSettlement> {
|
||||
running?.cancel()
|
||||
const run = runImportTask(input, {
|
||||
spawn,
|
||||
startTimeoutMs: IMPORT_START_TIMEOUT_MS,
|
||||
taskTimeoutMs: IMPORT_TIMEOUT_MS,
|
||||
})
|
||||
running = run
|
||||
void run.settled.then(() => {
|
||||
if (running === run) running = null
|
||||
})
|
||||
return run.settled
|
||||
}
|
||||
|
||||
/** Cancels the running import, if any (leaving Home, a second pick). */
|
||||
export function cancelImport(): void {
|
||||
running?.cancel()
|
||||
running = null
|
||||
}
|
||||
|
||||
/**
|
||||
* Warms the HTTP cache with the worker chunk (an immutable `/assets/` file) so that an
|
||||
* import works offline once the editor has loaded the engine, as it does today. Best
|
||||
* effort: a failure changes nothing.
|
||||
*/
|
||||
export function prefetchImportWorker(): void {
|
||||
if (
|
||||
prefetched ||
|
||||
typeof Worker === 'undefined' ||
|
||||
typeof fetch !== 'function'
|
||||
)
|
||||
return
|
||||
prefetched = true
|
||||
fetch(workerUrl, { credentials: 'same-origin' })
|
||||
.then((response) => response.body?.cancel())
|
||||
.catch(() => undefined)
|
||||
}
|
||||
|
||||
/** Test seam: run the worker logic in-process instead of a real `Worker`. */
|
||||
export function setImportWorkerSpawn(next: Spawn | null): void {
|
||||
spawn = next ?? spawnWorker
|
||||
}
|
||||
@@ -0,0 +1,150 @@
|
||||
import type { GlueFileBytes, GlueSheetHandle } from '@faunosteo/core-wasm'
|
||||
import { closedRefusal } from '@faunosteo/core-wasm'
|
||||
import {
|
||||
describeError,
|
||||
failureKindOf,
|
||||
PROTOCOL_VERSION,
|
||||
type ImportTaskKind,
|
||||
type ImportTaskMessage,
|
||||
type WorkerFailurePhase,
|
||||
type WorkerMessage,
|
||||
} from './protocol'
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
|
||||
/** What the glue gives once instantiated. */
|
||||
export interface WorkerEngine {
|
||||
SheetHandle: new (bundle: string) => GlueSheetHandle
|
||||
FileBytes: new (expected: number) => GlueFileBytes
|
||||
/** The instance's linear memory, for the diag. */
|
||||
memory: WebAssembly.Memory | null
|
||||
}
|
||||
|
||||
export type EngineLoader = (
|
||||
module: WebAssembly.Module | null,
|
||||
) => Promise<WorkerEngine>
|
||||
|
||||
/** The caps the worker checks before reading a byte (the core enforces the same). */
|
||||
export const MAX_PDF_BYTES = 50 * 1024 * 1024
|
||||
export const MAX_COPY_BYTES = 16 * 1024 * 1024
|
||||
|
||||
/** 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 })
|
||||
}
|
||||
|
||||
/** The sheet handle, or an error named `SheetRefused` carrying the module's refusal. */
|
||||
function sheetHandle(engine: WorkerEngine, sheet: string): GlueSheetHandle {
|
||||
try {
|
||||
return new engine.SheetHandle(sheet)
|
||||
} catch (error) {
|
||||
const detail = closedRefusal(error)
|
||||
if (detail === null) throw error
|
||||
const refused = new Error(detail)
|
||||
refused.name = 'SheetRefused'
|
||||
throw refused
|
||||
}
|
||||
}
|
||||
|
||||
interface Gathered {
|
||||
bytes: GlueFileBytes
|
||||
chunks: number
|
||||
}
|
||||
|
||||
/** 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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** 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 }
|
||||
}
|
||||
|
||||
/**
|
||||
* 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({
|
||||
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')
|
||||
)
|
||||
}
|
||||
@@ -0,0 +1,46 @@
|
||||
/// <reference lib="webworker" />
|
||||
import init, {
|
||||
FileBytes,
|
||||
SheetHandle,
|
||||
} from '@faunosteo/core-wasm/pkg/faunosteo_wasm.js'
|
||||
import wasmUrl from '@faunosteo/core-wasm/pkg/faunosteo_wasm_bg.wasm?url'
|
||||
import { createWorkerHandler, type WorkerEngine } from './handler'
|
||||
import { describeError, PROTOCOL_VERSION } from './protocol'
|
||||
|
||||
/**
|
||||
* The import worker entry (R4.3, plan §B.1.5 item 2): the glue is imported statically and
|
||||
* bundled into this chunk (a same-origin hashed asset the production CSP allows, no
|
||||
* `import()`, no recovery logic); the module is the compiled one the page posts, else the
|
||||
* asset fetched here. The listener is installed before any await; the whole life runs
|
||||
* inside the handler's try/catch, with `unhandledrejection` as a backstop: every throwable
|
||||
* reaches the page as one `failed` message. The page terminates the worker in every case.
|
||||
*/
|
||||
|
||||
const scope = self as unknown as DedicatedWorkerGlobalScope
|
||||
|
||||
const loadEngine = async (
|
||||
module: WebAssembly.Module | null,
|
||||
): Promise<WorkerEngine> => {
|
||||
const exports = (await init({ module_or_path: module ?? wasmUrl })) as {
|
||||
memory?: WebAssembly.Memory
|
||||
}
|
||||
return { SheetHandle, FileBytes, memory: exports.memory ?? null }
|
||||
}
|
||||
|
||||
const handle = createWorkerHandler(loadEngine, (message) =>
|
||||
scope.postMessage(message),
|
||||
)
|
||||
|
||||
scope.onmessage = (event: MessageEvent<unknown>) => {
|
||||
void handle(event.data)
|
||||
}
|
||||
|
||||
scope.onunhandledrejection = (event: PromiseRejectionEvent) => {
|
||||
scope.postMessage({
|
||||
v: PROTOCOL_VERSION,
|
||||
type: 'failed',
|
||||
phase: 'task',
|
||||
kind: 'other',
|
||||
detail: describeError(event.reason),
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,115 @@
|
||||
import type { ArchiveImport, DraftRestore } from '@faunosteo/core-wasm/types'
|
||||
import type { ImportSettlement, ImportTaskInput } from './client'
|
||||
|
||||
/**
|
||||
* What the import worker's settlement means for the page (R4.3, plan §B.1.8): the core's
|
||||
* outcome envelope mapped to the page's import error kinds, and the worker's own failures
|
||||
* classified so that a technical error, a resource overflow or a timeout is never shown as
|
||||
* a corrupt PDF (OD-5: `generic` for a PDF crash or timeout, `core_unavailable` for a copy).
|
||||
*/
|
||||
|
||||
export type ImportErrorKind =
|
||||
| 'invalid_pdf'
|
||||
| 'no_attachment'
|
||||
| 'attachment_stripped'
|
||||
| 'incompatible_version'
|
||||
| 'lone_surrogate'
|
||||
| 'invalid_copy'
|
||||
| 'core_unavailable'
|
||||
| 'generic'
|
||||
|
||||
export class ImportError extends Error {
|
||||
constructor(
|
||||
readonly kind: ImportErrorKind,
|
||||
/** The report version found, for `incompatible_version`. */
|
||||
readonly foundVersion: number | null = null,
|
||||
/** The technical reason, for the DEV console only. */
|
||||
readonly detail = '',
|
||||
) {
|
||||
super(kind)
|
||||
this.name = 'ImportError'
|
||||
}
|
||||
}
|
||||
|
||||
interface Envelope<T> {
|
||||
ok: boolean
|
||||
value?: T
|
||||
kind?: string
|
||||
found?: number
|
||||
detail?: string
|
||||
}
|
||||
|
||||
/** The envelope text, or `core_unavailable` when it is not one (never a trusted shape). */
|
||||
function parseEnvelope<T>(out: string): Envelope<T> {
|
||||
try {
|
||||
const parsed: unknown = JSON.parse(out)
|
||||
if (typeof parsed === 'object' && parsed !== null && 'ok' in parsed) {
|
||||
return parsed as Envelope<T>
|
||||
}
|
||||
} catch {
|
||||
// Not JSON: the module answered garbage, treated as an engine failure below.
|
||||
}
|
||||
throw new ImportError('core_unavailable', null, 'unreadable envelope')
|
||||
}
|
||||
|
||||
/** `SheetHandle.import_pdf` failures, one to one with today's kinds. */
|
||||
function pdfError(envelope: Envelope<unknown>): ImportError {
|
||||
switch (envelope.kind) {
|
||||
case 'invalid_pdf':
|
||||
case 'no_attachment':
|
||||
case 'attachment_stripped':
|
||||
case 'lone_surrogate':
|
||||
return new ImportError(envelope.kind, null, envelope.detail)
|
||||
case 'incompatible_version':
|
||||
return new ImportError('incompatible_version', envelope.found ?? null)
|
||||
case 'invalid':
|
||||
// The rebase refused the loaded sheet's reference: today's generic message.
|
||||
return new ImportError('generic', null, envelope.detail)
|
||||
default:
|
||||
return new ImportError('core_unavailable', null, envelope.detail)
|
||||
}
|
||||
}
|
||||
|
||||
/** Kinds that mean the copy itself cannot be read (`reportStore.UNREADABLE_DRAFT_KINDS`). */
|
||||
const UNREADABLE_COPY = new Set([
|
||||
'invalid',
|
||||
'unsupported_version',
|
||||
'lone_surrogate',
|
||||
])
|
||||
|
||||
function copyError(envelope: Envelope<unknown>): ImportError {
|
||||
if (UNREADABLE_COPY.has(envelope.kind ?? '')) {
|
||||
return new ImportError('invalid_copy', null, envelope.detail)
|
||||
}
|
||||
return new ImportError('core_unavailable', null, envelope.detail)
|
||||
}
|
||||
|
||||
/** The worker's own failures, by task (OD-5). */
|
||||
function workerError(
|
||||
task: ImportTaskInput['task'],
|
||||
settlement: ImportSettlement,
|
||||
): ImportError {
|
||||
if (settlement.kind !== 'failed') throw new Error('not a failure')
|
||||
const { reason, detail } = settlement
|
||||
if (reason === 'read') return new ImportError('generic', null, detail)
|
||||
if (task === 'pdf' && (reason === 'crashed' || reason === 'timeout')) {
|
||||
return new ImportError('generic', null, detail)
|
||||
}
|
||||
return new ImportError('core_unavailable', null, detail)
|
||||
}
|
||||
|
||||
/** The imported archive, or the ImportError the page shows. */
|
||||
export function pdfImportOf(settlement: ImportSettlement): ArchiveImport {
|
||||
if (settlement.kind === 'failed') throw workerError('pdf', settlement)
|
||||
const envelope = parseEnvelope<ArchiveImport>(settlement.out)
|
||||
if (!envelope.ok || envelope.value === undefined) throw pdfError(envelope)
|
||||
return envelope.value
|
||||
}
|
||||
|
||||
/** The restored copy, or the ImportError the page shows. */
|
||||
export function copyRestoreOf(settlement: ImportSettlement): DraftRestore {
|
||||
if (settlement.kind === 'failed') throw workerError('copy', settlement)
|
||||
const envelope = parseEnvelope<DraftRestore>(settlement.out)
|
||||
if (!envelope.ok || envelope.value === undefined) throw copyError(envelope)
|
||||
return envelope.value
|
||||
}
|
||||
@@ -0,0 +1,95 @@
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
|
||||
export const PROTOCOL_VERSION = 1
|
||||
|
||||
export type ImportTaskKind = 'pdf' | 'copy'
|
||||
|
||||
export interface ImportTaskMessage {
|
||||
v: typeof PROTOCOL_VERSION
|
||||
type: 'task'
|
||||
task: ImportTaskKind
|
||||
/** The picked file, never read on the page's thread. */
|
||||
file: File
|
||||
/** 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
|
||||
}
|
||||
|
||||
export interface WorkerReadyMessage {
|
||||
v: typeof PROTOCOL_VERSION
|
||||
type: 'ready'
|
||||
}
|
||||
|
||||
export interface WorkerResultMessage {
|
||||
v: typeof PROTOCOL_VERSION
|
||||
type: 'result'
|
||||
/** The outcome envelope text of the core (`{"ok":true,…}` or `{"ok":false,"kind":…}`). */
|
||||
out: string
|
||||
diag: ImportDiag
|
||||
}
|
||||
|
||||
/** Printed in DEV only, never sent anywhere. */
|
||||
export interface ImportDiag {
|
||||
ms: number
|
||||
linearBytes: number | null
|
||||
chunks: number
|
||||
}
|
||||
|
||||
export type WorkerFailurePhase = 'start' | 'task'
|
||||
|
||||
/**
|
||||
* `trap`: a `WebAssembly.RuntimeError`, or an engine stack overflow (`RangeError`,
|
||||
* `InternalError`); `read`: the file could not be read; `sheet`: the bundled sheet was
|
||||
* refused by the module; `other`: anything else (a glue or network failure at start).
|
||||
*/
|
||||
export type WorkerFailureKind = 'trap' | 'read' | 'sheet' | 'other'
|
||||
|
||||
export interface WorkerFailedMessage {
|
||||
v: typeof PROTOCOL_VERSION
|
||||
type: 'failed'
|
||||
phase: WorkerFailurePhase
|
||||
kind: WorkerFailureKind
|
||||
/** Error name and first message line, for the DEV console only. */
|
||||
detail: string
|
||||
}
|
||||
|
||||
export type WorkerMessage =
|
||||
| WorkerReadyMessage
|
||||
| WorkerResultMessage
|
||||
| WorkerFailedMessage
|
||||
|
||||
/** True for a message of this protocol, from a worker of the same build. */
|
||||
export function isWorkerMessage(data: unknown): data is WorkerMessage {
|
||||
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')
|
||||
)
|
||||
}
|
||||
|
||||
/** 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'
|
||||
const message = error instanceof Error ? error.message : String(error)
|
||||
return `${name}: ${message}`.split('\n')[0]!.slice(0, 200)
|
||||
}
|
||||
|
||||
/** The failure kind of a throwable, per §B.1.5 item 2. */
|
||||
export function failureKindOf(error: unknown): WorkerFailureKind {
|
||||
if (error instanceof WebAssembly.RuntimeError) return 'trap'
|
||||
if (!(error instanceof Error)) return 'other'
|
||||
if (error.name === 'RangeError' || error.name === 'InternalError')
|
||||
return 'trap'
|
||||
if (error.name === 'NotReadableError' || error.name === 'NotFoundError')
|
||||
return 'read'
|
||||
if (error.name === 'SheetRefused') return 'sheet'
|
||||
return 'other'
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
/**
|
||||
* A one-shot timer that stops counting while the page is hidden (R4.3, plan §B.1.5 item
|
||||
* 3): a phone that backgrounds the tab must not time an import out on return. The
|
||||
* visibility source is injected so tests drive it.
|
||||
*/
|
||||
|
||||
export interface Visibility {
|
||||
hidden(): boolean
|
||||
/** Calls `listener` on every change; returns the unsubscribe function. */
|
||||
onChange(listener: () => void): () => void
|
||||
}
|
||||
|
||||
export const documentVisibility: Visibility = {
|
||||
hidden: () =>
|
||||
typeof document !== 'undefined' && document.visibilityState === 'hidden',
|
||||
onChange: (listener) => {
|
||||
if (typeof document === 'undefined') return () => {}
|
||||
document.addEventListener('visibilitychange', listener)
|
||||
return () => document.removeEventListener('visibilitychange', listener)
|
||||
},
|
||||
}
|
||||
|
||||
export class PausableTimer {
|
||||
private remainingMs: number
|
||||
private startedAt: number | null = null
|
||||
private handle: ReturnType<typeof setTimeout> | null = null
|
||||
private readonly unsubscribe: () => void
|
||||
|
||||
constructor(
|
||||
durationMs: number,
|
||||
private readonly onElapsed: () => void,
|
||||
private readonly visibility: Visibility = documentVisibility,
|
||||
private readonly now: () => number = () => performance.now(),
|
||||
) {
|
||||
this.remainingMs = durationMs
|
||||
this.unsubscribe = visibility.onChange(() => this.sync())
|
||||
this.sync()
|
||||
}
|
||||
|
||||
/** Stops the timer for good; a timer never fires after it. */
|
||||
clear(): void {
|
||||
this.pause()
|
||||
this.unsubscribe()
|
||||
this.remainingMs = Number.POSITIVE_INFINITY
|
||||
}
|
||||
|
||||
private sync(): void {
|
||||
if (this.visibility.hidden()) this.pause()
|
||||
else this.resume()
|
||||
}
|
||||
|
||||
private resume(): void {
|
||||
if (this.handle !== null || !Number.isFinite(this.remainingMs)) return
|
||||
this.startedAt = this.now()
|
||||
this.handle = setTimeout(() => {
|
||||
this.handle = null
|
||||
this.remainingMs = 0
|
||||
this.unsubscribe()
|
||||
this.onElapsed()
|
||||
}, this.remainingMs)
|
||||
}
|
||||
|
||||
private pause(): void {
|
||||
if (this.handle === null) return
|
||||
clearTimeout(this.handle)
|
||||
this.handle = null
|
||||
if (this.startedAt !== null) {
|
||||
this.remainingMs = Math.max(
|
||||
0,
|
||||
this.remainingMs - (this.now() - this.startedAt),
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,11 +1,10 @@
|
||||
import type { ArchiveImport, RebaseOutcome } from '@faunosteo/core-wasm/types'
|
||||
import type { ArchiveImport } from '@faunosteo/core-wasm/types'
|
||||
import {
|
||||
ArchiveReadError,
|
||||
readAttachedDocument,
|
||||
type ArchiveReadErrorKind,
|
||||
} from '@faunosteo/pdf'
|
||||
import type { SheetIndex } from '@/services/sheetIndex'
|
||||
import { UNREADABLE_DRAFT_KINDS } from '@/state/reportStore'
|
||||
|
||||
export { MAX_ATTACHMENT_BYTES, MAX_PDF_BYTES } from '@faunosteo/pdf'
|
||||
|
||||
@@ -87,17 +86,3 @@ export async function importReportFromPdf(
|
||||
): Promise<ArchiveImport> {
|
||||
return importAttachment(await readAttachment(pdfBytes), index)
|
||||
}
|
||||
|
||||
/**
|
||||
* A rescue copy (`JSON.stringify(report)`, the byte format of the tab's draft)
|
||||
* read by the core's draft restore, no archive beside it. Content the core
|
||||
* refuses is `invalid_copy`; any other failure is the engine's or the sheet's.
|
||||
*/
|
||||
export function readRescueCopy(text: string, index: SheetIndex): RebaseOutcome {
|
||||
const outcome = index.ops.restoreDraft(text, null)
|
||||
if (outcome.ok) return outcome.value.rebase
|
||||
if (UNREADABLE_DRAFT_KINDS.has(outcome.kind)) {
|
||||
throw new ImportError('invalid_copy')
|
||||
}
|
||||
throw new ImportError('core_unavailable')
|
||||
}
|
||||
@@ -1,6 +1,7 @@
|
||||
import { useEffect, useState } from 'react'
|
||||
import type { SheetIndexData } from '@faunosteo/core-wasm/types'
|
||||
import { coreRuntime } from '@/core/runtime'
|
||||
import { prefetchImportWorker } from '@/core/worker/controller'
|
||||
import { SheetOps } from '@/core/sheetOps'
|
||||
import { SheetIndex } from '@/services/sheetIndex'
|
||||
import {
|
||||
@@ -50,10 +51,13 @@ async function loadIntoCore(speciesId: string): Promise<SheetLoad> {
|
||||
const data = session.call<SheetIndexData>('index_data', '')
|
||||
if (data.ok) {
|
||||
const index = new SheetIndex(data.value, new SheetOps(session))
|
||||
// The engine is loaded: warm the import worker's chunk for a later offline import.
|
||||
prefetchImportWorker()
|
||||
return { status: 'ready', index }
|
||||
}
|
||||
return {
|
||||
status: data.kind === 'invalid_sheet' ? 'invalid_sheet' : 'core_unavailable',
|
||||
status:
|
||||
data.kind === 'invalid_sheet' ? 'invalid_sheet' : 'core_unavailable',
|
||||
}
|
||||
}
|
||||
|
||||
@@ -73,6 +77,17 @@ export function loadSheet(speciesId: string): Promise<SheetLoad> {
|
||||
return pending
|
||||
}
|
||||
|
||||
/**
|
||||
* The bundled payload as the text the core's `SheetHandle` reads, for the import worker
|
||||
* (R4.3): the same text the page's own session was built from. Null without a sheet.
|
||||
*/
|
||||
export async function loadSheetBundleText(
|
||||
speciesId: string,
|
||||
): Promise<string | null> {
|
||||
const bundle = await provider.getReferenceSheet(speciesId)
|
||||
return bundle ? JSON.stringify(bundle) : null
|
||||
}
|
||||
|
||||
/** The ready index, or null (tests and callers that need the sheet or nothing). */
|
||||
export async function loadSheetIndex(
|
||||
speciesId: string,
|
||||
@@ -99,7 +114,8 @@ export function useSheet(speciesId: string | undefined): SheetState {
|
||||
void loadSheet(speciesId).then((load) => {
|
||||
if (cancelled) return
|
||||
if (load.status === 'ready' || load.status === 'none') setState(load)
|
||||
else if (load.status === 'invalid_sheet') setState({ status: load.status, retry })
|
||||
else if (load.status === 'invalid_sheet')
|
||||
setState({ status: load.status, retry })
|
||||
else setState({ status: 'core_unavailable', retry })
|
||||
})
|
||||
return () => {
|
||||
|
||||
Reference in new issue
Block a user