toiljs 0.0.15 → 0.0.19

package/presets/no-uint8array-tostring.js

@@ -1,200 +1,200 @@
-/**
- * ESLint rule: disallow `.toString()` on Uint8Array (and branded byte types), which returns
- * comma-separated decimals instead of hex.
- */
-import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils';
-import { SyntaxKind } from 'typescript';
-
-function isUint8ArrayType(type, checker) {
-    const symbol = type.getSymbol();
-    if (symbol?.getName() === 'Uint8Array') {
-        return true;
-    }
-
-    const baseTypes = type.getBaseTypes?.();
-    if (baseTypes) {
-        for (const baseType of baseTypes) {
-            if (isUint8ArrayType(baseType, checker)) {
-                return true;
-            }
-        }
-    }
-
-    if (type.isIntersection()) {
-        for (const subType of type.types) {
-            if (isUint8ArrayType(subType, checker)) {
-                return true;
-            }
-        }
-    }
-
-    if (type.isUnion()) {
-        return (
-            type.types.length > 0 &&
-            type.types.every((subType) => isUint8ArrayType(subType, checker))
-        );
-    }
-
-    const constraint = type.getConstraint?.();
-    if (constraint && isUint8ArrayType(constraint, checker)) {
-        return true;
-    }
-
-    return false;
-}
-
-/**
- * Types whose toString() is the dangerous default behavior we want to catch.
- * If toString is declared on any type NOT in this set, it has been
- * intentionally overridden and we should leave it alone.
- */
-const DEFAULT_TOSTRING_OWNERS = new Set([
-    'Object',
-    'Uint8Array',
-    'Int8Array',
-    'Uint8ClampedArray',
-    'Int16Array',
-    'Uint16Array',
-    'Int32Array',
-    'Uint32Array',
-    'Float32Array',
-    'Float64Array',
-    'BigInt64Array',
-    'BigUint64Array',
-]);
-
-/**
- * Given a declaration node, walk up the AST parents to find the enclosing
- * class or interface name. More reliable than checker.getTypeAtLocation(decl.parent),
- * which can return odd results for .d.ts files.
- */
-function getEnclosingClassName(decl) {
-    let current = decl.parent;
-    while (current) {
-        if (
-            current.kind === SyntaxKind.ClassDeclaration ||
-            current.kind === SyntaxKind.ClassExpression ||
-            current.kind === SyntaxKind.InterfaceDeclaration
-        ) {
-            if (current.name) {
-                return current.name.text;
-            }
-        }
-
-        current = current.parent;
-    }
-
-    return undefined;
-}
-
-/**
- * Checks whether the resolved toString() on this type is a custom override
- * rather than the default Uint8Array/Object prototype version.
- */
-function hasCustomToString(type, checker) {
-    const toStringSymbol = type.getProperty('toString');
-    if (!toStringSymbol) {
-        return false;
-    }
-
-    const declarations = toStringSymbol.getDeclarations();
-    if (!declarations || declarations.length === 0) {
-        return false;
-    }
-
-    for (const decl of declarations) {
-        const ownerName = getEnclosingClassName(decl);
-        if (ownerName && !DEFAULT_TOSTRING_OWNERS.has(ownerName)) {
-            return true;
-        }
-    }
-
-    const apparentType = checker.getApparentType(type);
-    if (apparentType !== type) {
-        const apparentToString = apparentType.getProperty('toString');
-        if (apparentToString && apparentToString !== toStringSymbol) {
-            const apparentDecls = apparentToString.getDeclarations();
-            if (apparentDecls) {
-                for (const decl of apparentDecls) {
-                    const ownerName = getEnclosingClassName(decl);
-                    if (ownerName && !DEFAULT_TOSTRING_OWNERS.has(ownerName)) {
-                        return true;
-                    }
-                }
-            }
-        }
-    }
-
-    return false;
-}
-
-const createRule = ESLintUtils.RuleCreator(
-    (name) => `https://github.com/dacely-cloud/toiljs/tree/main/presets#${name}`,
-);
-
-const rule = createRule({
-    name: 'no-uint8array-tostring',
-    meta: {
-        type: 'problem',
-        docs: {
-            description:
-                'Disallow .toString() on Uint8Array and branded types (Script, Bytes32, etc.) which produces comma-separated decimals instead of hex',
-        },
-        messages: {
-            noUint8ArrayToString:
-                '{{typeName}}.toString() returns comma-separated decimals (e.g. "0,32,70,107"), not a hex string. ' +
-                'Use Buffer.from(arr).toString("hex") or toHex() instead.',
-        },
-        schema: [],
-    },
-    defaultOptions: [],
-    create(context) {
-        const services = ESLintUtils.getParserServices(context);
-        const checker = services.program.getTypeChecker();
-
-        return {
-            CallExpression(node) {
-                if (
-                    node.callee.type !== AST_NODE_TYPES.MemberExpression ||
-                    node.callee.property.type !== AST_NODE_TYPES.Identifier ||
-                    node.callee.property.name !== 'toString' ||
-                    node.arguments.length > 0
-                ) {
-                    return;
-                }
-
-                const objectNode = node.callee.object;
-                const tsNode = services.esTreeNodeToTSNodeMap.get(objectNode);
-                const type = checker.getTypeAtLocation(tsNode);
-
-                if (!isUint8ArrayType(type, checker)) {
-                    return;
-                }
-
-                if (hasCustomToString(type, checker)) {
-                    return;
-                }
-
-                const typeName = checker.typeToString(type);
-                context.report({
-                    node,
-                    messageId: 'noUint8ArrayToString',
-                    data: { typeName },
-                });
-            },
-        };
-    },
-});
-
-const plugin = {
-    meta: {
-        name: 'eslint-plugin-no-uint8array-tostring',
-        version: '1.0.0',
-    },
-    rules: {
-        'no-uint8array-tostring': rule,
-    },
-};
-
-export default plugin;
-export { rule };
+/**
+ * ESLint rule: disallow `.toString()` on Uint8Array (and branded byte types), which returns
+ * comma-separated decimals instead of hex.
+ */
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils';
+import { SyntaxKind } from 'typescript';
+
+function isUint8ArrayType(type, checker) {
+    const symbol = type.getSymbol();
+    if (symbol?.getName() === 'Uint8Array') {
+        return true;
+    }
+
+    const baseTypes = type.getBaseTypes?.();
+    if (baseTypes) {
+        for (const baseType of baseTypes) {
+            if (isUint8ArrayType(baseType, checker)) {
+                return true;
+            }
+        }
+    }
+
+    if (type.isIntersection()) {
+        for (const subType of type.types) {
+            if (isUint8ArrayType(subType, checker)) {
+                return true;
+            }
+        }
+    }
+
+    if (type.isUnion()) {
+        return (
+            type.types.length > 0 &&
+            type.types.every((subType) => isUint8ArrayType(subType, checker))
+        );
+    }
+
+    const constraint = type.getConstraint?.();
+    if (constraint && isUint8ArrayType(constraint, checker)) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Types whose toString() is the dangerous default behavior we want to catch.
+ * If toString is declared on any type NOT in this set, it has been
+ * intentionally overridden and we should leave it alone.
+ */
+const DEFAULT_TOSTRING_OWNERS = new Set([
+    'Object',
+    'Uint8Array',
+    'Int8Array',
+    'Uint8ClampedArray',
+    'Int16Array',
+    'Uint16Array',
+    'Int32Array',
+    'Uint32Array',
+    'Float32Array',
+    'Float64Array',
+    'BigInt64Array',
+    'BigUint64Array',
+]);
+
+/**
+ * Given a declaration node, walk up the AST parents to find the enclosing
+ * class or interface name. More reliable than checker.getTypeAtLocation(decl.parent),
+ * which can return odd results for .d.ts files.
+ */
+function getEnclosingClassName(decl) {
+    let current = decl.parent;
+    while (current) {
+        if (
+            current.kind === SyntaxKind.ClassDeclaration ||
+            current.kind === SyntaxKind.ClassExpression ||
+            current.kind === SyntaxKind.InterfaceDeclaration
+        ) {
+            if (current.name) {
+                return current.name.text;
+            }
+        }
+
+        current = current.parent;
+    }
+
+    return undefined;
+}
+
+/**
+ * Checks whether the resolved toString() on this type is a custom override
+ * rather than the default Uint8Array/Object prototype version.
+ */
+function hasCustomToString(type, checker) {
+    const toStringSymbol = type.getProperty('toString');
+    if (!toStringSymbol) {
+        return false;
+    }
+
+    const declarations = toStringSymbol.getDeclarations();
+    if (!declarations || declarations.length === 0) {
+        return false;
+    }
+
+    for (const decl of declarations) {
+        const ownerName = getEnclosingClassName(decl);
+        if (ownerName && !DEFAULT_TOSTRING_OWNERS.has(ownerName)) {
+            return true;
+        }
+    }
+
+    const apparentType = checker.getApparentType(type);
+    if (apparentType !== type) {
+        const apparentToString = apparentType.getProperty('toString');
+        if (apparentToString && apparentToString !== toStringSymbol) {
+            const apparentDecls = apparentToString.getDeclarations();
+            if (apparentDecls) {
+                for (const decl of apparentDecls) {
+                    const ownerName = getEnclosingClassName(decl);
+                    if (ownerName && !DEFAULT_TOSTRING_OWNERS.has(ownerName)) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+
+    return false;
+}
+
+const createRule = ESLintUtils.RuleCreator(
+    (name) => `https://github.com/dacely-cloud/toiljs/tree/main/presets#${name}`,
+);
+
+const rule = createRule({
+    name: 'no-uint8array-tostring',
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Disallow .toString() on Uint8Array and branded types (Script, Bytes32, etc.) which produces comma-separated decimals instead of hex',
+        },
+        messages: {
+            noUint8ArrayToString:
+                '{{typeName}}.toString() returns comma-separated decimals (e.g. "0,32,70,107"), not a hex string. ' +
+                'Use Buffer.from(arr).toString("hex") or toHex() instead.',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        const services = ESLintUtils.getParserServices(context);
+        const checker = services.program.getTypeChecker();
+
+        return {
+            CallExpression(node) {
+                if (
+                    node.callee.type !== AST_NODE_TYPES.MemberExpression ||
+                    node.callee.property.type !== AST_NODE_TYPES.Identifier ||
+                    node.callee.property.name !== 'toString' ||
+                    node.arguments.length > 0
+                ) {
+                    return;
+                }
+
+                const objectNode = node.callee.object;
+                const tsNode = services.esTreeNodeToTSNodeMap.get(objectNode);
+                const type = checker.getTypeAtLocation(tsNode);
+
+                if (!isUint8ArrayType(type, checker)) {
+                    return;
+                }
+
+                if (hasCustomToString(type, checker)) {
+                    return;
+                }
+
+                const typeName = checker.typeToString(type);
+                context.report({
+                    node,
+                    messageId: 'noUint8ArrayToString',
+                    data: { typeName },
+                });
+            },
+        };
+    },
+});
+
+const plugin = {
+    meta: {
+        name: 'eslint-plugin-no-uint8array-tostring',
+        version: '1.0.0',
+    },
+    rules: {
+        'no-uint8array-tostring': rule,
+    },
+};
+
+export default plugin;
+export { rule };

package/presets/prettier-plugin.js

@@ -0,0 +1,51 @@
+/**
+ * Prettier plugin that lets prettier format toilscript server code, which uses native
+ * decorators on free functions (`@main`, `@remote function ...`). Those are valid
+ * toilscript but not valid ECMAScript/TypeScript grammar, so prettier's parser rejects
+ * them outright.
+ *
+ * The fix is a parse-time/print-time round-trip: in `preprocess` each function decorator
+ * is rewritten to a marker block comment (which the TS parser accepts), and the estree
+ * printer's `printComment` renders that marker back as the original `@decorator`. Class
+ * and method decorators are already valid grammar and pass through untouched.
+ */
+import * as tsPlugin from 'prettier/plugins/typescript';
+import * as estreePlugin from 'prettier/plugins/estree';
+
+const baseTs = tsPlugin.parsers.typescript;
+const baseEstree = estreePlugin.printers.estree;
+
+const MARKER = '::toil-decorator ';
+// One-or-more bare decorators (`@name`, no args) immediately before a function declaration.
+const FN_DECORATORS =
+    /((?:@[A-Za-z_$][\w$]*[ \t]*\r?\n[ \t]*)+)((?:export[ \t]+)?(?:default[ \t]+)?(?:async[ \t]+)?function\b)/g;
+const ONE_DECORATOR = /@([A-Za-z_$][\w$]*)([ \t]*\r?\n[ \t]*)/g;
+
+function preprocess(text, options) {
+    const pre = baseTs.preprocess ? baseTs.preprocess(text, options) : text;
+    return pre.replace(FN_DECORATORS, (_match, decorators, fn) => {
+        const masked = decorators.replace(
+            ONE_DECORATOR,
+            (_d, name, gap) => `/*${MARKER}${name}*/${gap}`,
+        );
+        return masked + fn;
+    });
+}
+
+export const parsers = {
+    typescript: { ...baseTs, preprocess },
+};
+
+export const printers = {
+    estree: {
+        ...baseEstree,
+        printComment(path, options) {
+            const comment = path.node ?? path.getValue();
+            const value = comment?.value;
+            if (typeof value === 'string' && value.startsWith(MARKER)) {
+                return '@' + value.slice(MARKER.length).trim();
+            }
+            return baseEstree.printComment(path, options);
+        },
+    },
+};

package/presets/prettier.json

@@ -1,18 +1,19 @@
-{
-    "printWidth": 120,
-    "tabWidth": 4,
-    "useTabs": false,
-    "semi": true,
-    "singleQuote": true,
-    "trailingComma": "none",
-    "bracketSpacing": true,
-    "bracketSameLine": true,
-    "arrowParens": "always",
-    "htmlWhitespaceSensitivity": "css",
-    "overrides": [
-        {
-            "files": "*.html",
-            "options": { "parser": "html" }
-        }
-    ]
-}
+{
+    "plugins": ["toiljs/prettier-plugin"],
+    "printWidth": 120,
+    "tabWidth": 4,
+    "useTabs": false,
+    "semi": true,
+    "singleQuote": true,
+    "trailingComma": "none",
+    "bracketSpacing": true,
+    "bracketSameLine": true,
+    "arrowParens": "always",
+    "htmlWhitespaceSensitivity": "css",
+    "overrides": [
+        {
+            "files": "*.html",
+            "options": { "parser": "html" }
+        }
+    ]
+}

package/presets/tsconfig.json

@@ -1,37 +1,37 @@
-// toiljs shared client tsconfig, opinionated, strict.
-// Extend it from your project: { "extends": "toiljs/tsconfig", "include": ["client", ".toil"] }
-{
-    "compilerOptions": {
-        "strict": true,
-        "noImplicitAny": true,
-        "strictNullChecks": true,
-        "strictFunctionTypes": true,
-        "strictBindCallApply": true,
-        "strictPropertyInitialization": true,
-        "noImplicitThis": true,
-        "useUnknownInCatchVariables": true,
-        "alwaysStrict": true,
-        "noUnusedLocals": true,
-        "noUnusedParameters": true,
-        "exactOptionalPropertyTypes": false,
-        "noImplicitReturns": false,
-        "noFallthroughCasesInSwitch": true,
-        "noUncheckedIndexedAccess": false,
-        "noImplicitOverride": true,
-        "noPropertyAccessFromIndexSignature": false,
-        "module": "ES2020",
-        "target": "ES2020",
-        "moduleResolution": "Bundler",
-        "jsx": "react-jsx",
-        "lib": ["ESNext", "DOM", "DOM.Iterable", "DOM.AsyncIterable"],
-        "isolatedModules": true,
-        "verbatimModuleSyntax": false,
-        "allowImportingTsExtensions": true,
-        "esModuleInterop": true,
-        "resolveJsonModule": true,
-        "forceConsistentCasingInFileNames": true,
-        "skipLibCheck": true,
-        "moduleDetection": "force",
-        "noEmit": true
-    }
-}
+// toiljs shared client tsconfig, opinionated, strict.
+// Extend it from your project: { "extends": "toiljs/tsconfig", "include": ["client", ".toil"] }
+{
+    "compilerOptions": {
+        "strict": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "strictBindCallApply": true,
+        "strictPropertyInitialization": true,
+        "noImplicitThis": true,
+        "useUnknownInCatchVariables": true,
+        "alwaysStrict": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "exactOptionalPropertyTypes": false,
+        "noImplicitReturns": false,
+        "noFallthroughCasesInSwitch": true,
+        "noUncheckedIndexedAccess": false,
+        "noImplicitOverride": true,
+        "noPropertyAccessFromIndexSignature": false,
+        "module": "ES2020",
+        "target": "ES2020",
+        "moduleResolution": "Bundler",
+        "jsx": "react-jsx",
+        "lib": ["ESNext", "DOM", "DOM.Iterable", "DOM.AsyncIterable"],
+        "isolatedModules": true,
+        "verbatimModuleSyntax": false,
+        "allowImportingTsExtensions": true,
+        "esModuleInterop": true,
+        "resolveJsonModule": true,
+        "forceConsistentCasingInFileNames": true,
+        "skipLibCheck": true,
+        "moduleDetection": "force",
+        "noEmit": true
+    }
+}

package/server/runtime/README.md

@@ -0,0 +1,97 @@
+# toiljs server runtime
+
+In-tree SDK that bridges a toilscript handler to the toil-backend
+edge's wasm ABI.
+
+## What it does
+
+The edge calls `handle(req_ofs: i32, req_len: i32) -> i64` on every
+request. This runtime gives you:
+
+- `Request` / `Response` AssemblyScript types
+- A byte-for-byte envelope codec matching
+  `toil-backend/src/http/envelope.rs`
+- A `ToilHandler` base class you extend, plus a `Server` singleton you
+  assign `Server.handler = () => new MyHandler()`. The `handle` wasm
+  export (re-exported from `toiljs/server/runtime/exports`) decodes the
+  request, runs your handler, encodes the response, and returns the
+  packed i64 the host expects.
+
+## Wire contract
+
+Source of truth: `toil-backend/src/http/envelope.rs`.
+
+```
+request envelope (LE, no padding):
+  u8   method      0=GET 1=POST 2=PUT 3=DELETE 4=PATCH 5=HEAD 6=OPTIONS
+  u16  path_len
+  [u8] path
+  u16  n_headers
+  for each header: u16 name_len, u16 val_len, [u8] name, [u8] val
+  u32  body_len
+  [u8] body
+```
+
+The response envelope is the same shape with the first `u8 method +
+u16 path_len + path` replaced by `u16 status`.
+
+The handler must return a packed `i64`:
+
+```
+(resp_ofs << 32) | resp_len
+```
+
+The host reads `resp_len` bytes starting at `resp_ofs` in linear
+memory and decodes them as a response envelope.
+
+## Memory layout
+
+- `[0, req_len)` — request envelope, written by the host before
+  `handle` is called.
+- `[65536, 65536 + resp_len)` — response envelope, written by
+  `dispatch` (the response base is the second 64 KiB page so the
+  request and response never overlap).
+
+The edge enforces a 1024-page (64 MiB) linear memory cap via
+`LimitingTunables`, so leaving the first page for the request is
+fine.
+
+## Example
+
+A user app extends `ToilHandler` and wires it up in `server/main.ts`.
+The runtime is consumed as the `toiljs/server/runtime` library export:
+
+```ts
+// server/HelloHandler.ts
+import { ToilHandler, Request, Response } from 'toiljs/server/runtime';
+
+export class HelloHandler extends ToilHandler {
+    public handle(req: Request): Response {
+        if (req.path == '/') return Response.text('hello\n');
+        if (req.path == '/json') return Response.json('{"ok":true}');
+        return Response.notFound();
+    }
+}
+```
+
+```ts
+// server/main.ts
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import { HelloHandler } from './HelloHandler';
+
+Server.handler = () => new HelloHandler();
+
+// Surface the wasm `handle(i32, i32) -> i64` entry the edge calls.
+export * from 'toiljs/server/runtime/exports';
+
+// Forward AS runtime panics to the host's env::abort import.
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}
+```
+
+Compile with `toilscript --target release`, drop the resulting
+`build/server/release.wasm` at `<toil-backend>/hosts/<hostname>.wasm`,
+and the edge will route requests with that `Host:` header to it. A
+complete app lives in `examples/basic`.