@abide/abide 0.58.0 → 0.101.0

package/src/server/muxUpgrade.ts

@@ -0,0 +1,72 @@
+// 18.1, 37.3 — THE MUX'S UPGRADE, both halves of it: the app lane admitting it, and a listener — `App.listen`,
+// or `abide dev`'s worker telling its listener — reading that admission off the lane's answer and
+// performing it.
+//
+// THE ADMISSION IS A STATUS, NOT AN IDENTITY: a rung runs around the lane (37.3) and one that rebuilds
+// the answer to lay a header over it has still let the lane answer. So the listener asks the one
+// question the lane did, of the request as it arrived, and upgrades only where the answer still
+// carries the status the lane admits with — a rung answering in the lane's place answers something
+// else, and one answering an upgrade at any other address opens nothing.
+
+import { SOCKET_ADDRESS } from '#shared/ADDRESSES.ts'
+import { unmounted } from '#shared/mount.ts'
+import { plainAnswer } from './plainAnswer.ts'
+
+const MUX_ADMITTED = 204
+
+// What the mux carries: an app with no handler has no mux to open.
+type Carried = { handlers: { size: number } }
+
+/** Whether `request` is the mux's upgrade, at `pathname` below the mount. */
+function asksForMux(
+    pathname: string,
+    request: Request,
+    carried: Carried,
+): boolean {
+    return (
+        pathname === SOCKET_ADDRESS &&
+        request.headers.get('upgrade') === 'websocket' &&
+        carried.handlers.size > 0
+    )
+}
+
+/**
+ * The app lane's answer to the mux's upgrade, or `undefined` where `request` is not one.
+ *
+ * 37.3 — arriving at the lane is the app's middleware having let the upgrade through.
+ */
+export function muxAdmission(
+    asked: string,
+    request: Request,
+    carried: Carried,
+): Response | undefined {
+    return asksForMux(asked, request, carried)
+        ? new Response(null, { status: MUX_ADMITTED })
+        : undefined
+}
+
+/**
+ * Whether the request is upgraded to the socket mux, given what the app lane answered it.
+ *
+ * 16.10 — read below the mount, as every other request's address is.
+ */
+export function admitsMux(
+    request: Request,
+    answered: Response,
+    carried: Carried,
+): boolean {
+    if (answered.status !== MUX_ADMITTED) return false
+    const pathname = new URL(request.url).pathname
+    return asksForMux(unmounted(pathname) ?? pathname, request, carried)
+}
+
+/** The upgrade performed, carrying `data`: nothing to answer, or the refusal of a request that was no websocket. */
+export function upgraded<Data>(
+    server: { upgrade(request: Request, options: { data: Data }): boolean },
+    request: Request,
+    data: Data,
+): Response | undefined {
+    return server.upgrade(request, { data })
+        ? undefined
+        : plainAnswer('expected a websocket', 400)
+}

package/src/server/namesUnder.ts

@@ -0,0 +1,15 @@
+/**
+ * The paths below `directory` that `pattern` matches, or none for a directory that is not there.
+ *
+ * A missing directory is the common case rather than an error: an app has no `ui/public` or
+ * `server/rpc` until its author adds one. Narrowed to that one code for `shellUnder`'s reason: a
+ * directory that exists and cannot be read is a different fault and must not read as an empty one.
+ */
+export function namesUnder(directory: string, pattern = '**/*'): string[] {
+    try {
+        return [...new Bun.Glob(pattern).scanSync({ cwd: directory })]
+    } catch (thrown) {
+        if ((thrown as { code?: unknown }).code !== 'ENOENT') throw thrown
+        return []
+    }
+}

package/src/server/nativeMenu.ts

@@ -0,0 +1,296 @@
+// THE DESKTOP APP'S MENU BAR (38.89): the default, with what the page the window shows exports,
+// built as an `NSMenu`.
+
+import { FFIType } from 'bun:ffi'
+import type { MenuRole } from '#shared/menuItem.ts'
+import {
+    definedClass,
+    type Id,
+    nsString,
+    objcClass,
+    selector,
+    send,
+    sendTyped,
+} from './appKit.ts'
+
+/**
+ * A menu item as the window builds it: the defaults, and what a page told it (`reportMenu`), each
+ * item the page answers numbered by `id`.
+ */
+export type NativeItem =
+    | 'separator'
+    | {
+          label: string
+          key?: string | undefined
+          role?: MenuRole | undefined
+          id?: number | undefined
+          items?: NativeItem[] | undefined
+      }
+
+// 38.90 — A ROLE AppKit ALREADY ANSWERS is sent down the responder chain, so `copy` copies whatever
+// holds the selection and is greyed where nothing does. The rest are the launcher's own.
+const RESPONDER_ROLES: Partial<Record<MenuRole, string>> = {
+    about: 'orderFrontStandardAboutPanel:',
+    hide: 'hide:',
+    hideOthers: 'hideOtherApplications:',
+    showAll: 'unhideAllApplications:',
+    quit: 'terminate:',
+    close: 'performClose:',
+    undo: 'undo:',
+    redo: 'redo:',
+    cut: 'cut:',
+    copy: 'copy:',
+    paste: 'paste:',
+    selectAll: 'selectAll:',
+    fullscreen: 'toggleFullScreen:',
+    minimize: 'performMiniaturize:',
+    zoom: 'performZoom:',
+    front: 'arrangeInFront:',
+}
+
+const MODIFIERS: Record<string, number> = {
+    shift: 1 << 17,
+    ctrl: 1 << 18,
+    control: 1 << 18,
+    alt: 1 << 19,
+    option: 1 << 19,
+    cmd: 1 << 20,
+    command: 1 << 20,
+}
+
+const NAMED_KEYS: Record<string, string> = {
+    enter: '\r',
+    return: '\r',
+    tab: '\t',
+    escape: '\x1b',
+    esc: '\x1b',
+    backspace: '\b',
+    delete: '\x7f',
+    space: ' ',
+    up: '',
+    down: '',
+    left: '',
+    right: '',
+}
+
+/**
+ * The menu bar the window shows: the application, File, Edit, View and Window menus, and `added`.
+ *
+ * 38.89 — AN ADDED MENU NAMED AS A DEFAULT ONE GROWS IT, and any other stands before Window, where
+ * the platform puts an app's own. 38.84 — no Connect… where `launcher.json` turns connecting off.
+ */
+export function menuBar(
+    appName: string,
+    connect: boolean,
+    added: NativeItem[],
+): NativeItem[] {
+    const bar = defaultMenu(appName, connect)
+    const window = bar.pop() as NativeItem
+    for (const menu of added) {
+        const named =
+            menu === 'separator'
+                ? undefined
+                : bar.find(
+                      (standing) =>
+                          standing !== 'separator' &&
+                          standing.label === menu.label,
+                  )
+        if (
+            named === undefined ||
+            named === 'separator' ||
+            menu === 'separator'
+        )
+            bar.push(menu)
+        else named.items = [...(named.items ?? []), ...(menu.items ?? [])]
+    }
+    bar.push(window)
+    return bar
+}
+
+function defaultMenu(appName: string, connect: boolean): NativeItem[] {
+    return [
+        {
+            label: appName,
+            items: [
+                { label: `About ${appName}`, role: 'about' },
+                'separator',
+                { label: `Hide ${appName}`, role: 'hide', key: 'cmd+h' },
+                { label: 'Hide Others', role: 'hideOthers', key: 'cmd+alt+h' },
+                { label: 'Show All', role: 'showAll' },
+                'separator',
+                { label: `Quit ${appName}`, role: 'quit', key: 'cmd+q' },
+            ],
+        },
+        {
+            label: 'File',
+            items: [
+                ...(connect
+                    ? ([
+                          { label: 'Connect…', role: 'connect', key: 'cmd+k' },
+                      ] as NativeItem[])
+                    : []),
+                { label: 'Disconnect', role: 'disconnect', key: 'cmd+shift+k' },
+                'separator',
+                { label: 'Close Window', role: 'close', key: 'cmd+w' },
+            ],
+        },
+        {
+            label: 'Edit',
+            items: [
+                { label: 'Undo', role: 'undo', key: 'cmd+z' },
+                { label: 'Redo', role: 'redo', key: 'cmd+shift+z' },
+                'separator',
+                { label: 'Cut', role: 'cut', key: 'cmd+x' },
+                { label: 'Copy', role: 'copy', key: 'cmd+c' },
+                { label: 'Paste', role: 'paste', key: 'cmd+v' },
+                { label: 'Select All', role: 'selectAll', key: 'cmd+a' },
+            ],
+        },
+        {
+            label: 'View',
+            items: [
+                { label: 'Reload', role: 'reload', key: 'cmd+r' },
+                'separator',
+                {
+                    label: 'Enter Full Screen',
+                    role: 'fullscreen',
+                    key: 'ctrl+cmd+f',
+                },
+            ],
+        },
+        {
+            label: 'Window',
+            items: [
+                { label: 'Minimize', role: 'minimize', key: 'cmd+m' },
+                { label: 'Zoom', role: 'zoom' },
+                'separator',
+                { label: 'Bring All to Front', role: 'front' },
+            ],
+        },
+    ]
+}
+
+type Choice = Exclude<NativeItem, 'separator'>
+
+// What each launcher-handled item fires, by the tag its `NSMenuItem` carries.
+let chosen: Choice[] = []
+let onChoice: (item: Choice) => void = () => {}
+let target: Id = null
+
+/**
+ * Builds `menu` as the application's menu bar; `choose` is handed each item AppKit does not answer
+ * itself when it is picked.
+ */
+export function installMenu(
+    menu: NativeItem[],
+    choose: (item: Choice) => void,
+): void {
+    target ??= send(
+        definedClass('AbideMenuTarget', {
+            'choose:': {
+                types: 'v@:@',
+                args: [FFIType.ptr],
+                returns: FFIType.void,
+                run: (item: Id) => {
+                    const picked =
+                        chosen[
+                            Number(
+                                sendTyped(
+                                    item,
+                                    'tag',
+                                    [],
+                                    FFIType.i64,
+                                ) as bigint,
+                            )
+                        ]
+                    if (picked !== undefined) onChoice(picked)
+                },
+            },
+        }),
+        'new',
+    )
+    chosen = []
+    onChoice = choose
+    const bar = send(objcClass('NSMenu'), 'new')
+    for (const item of menu) send(bar, 'addItem:', menuItem(item))
+    send(
+        send(objcClass('NSApplication'), 'sharedApplication'),
+        'setMainMenu:',
+        bar,
+    )
+}
+
+function menuItem(item: NativeItem): Id {
+    if (item === 'separator')
+        return send(objcClass('NSMenuItem'), 'separatorItem')
+    const { keyEquivalent, modifiers } = shortcut(item.key)
+    const responder =
+        item.role === undefined ? undefined : RESPONDER_ROLES[item.role]
+    const built = send(
+        send(objcClass('NSMenuItem'), 'alloc'),
+        'initWithTitle:action:keyEquivalent:',
+        nsString(item.label),
+        null,
+        nsString(keyEquivalent),
+    )
+    sendTyped(
+        built,
+        'setKeyEquivalentModifierMask:',
+        [FFIType.u64],
+        FFIType.void,
+        modifiers,
+    )
+    if (item.items !== undefined) {
+        const submenu = send(
+            send(objcClass('NSMenu'), 'alloc'),
+            'initWithTitle:',
+            nsString(item.label),
+        )
+        for (const child of item.items)
+            send(submenu, 'addItem:', menuItem(child))
+        send(built, 'setSubmenu:', submenu)
+        return built
+    }
+    if (responder !== undefined) {
+        sendTyped(
+            built,
+            'setAction:',
+            [FFIType.ptr],
+            FFIType.void,
+            selector(responder),
+        )
+        return built
+    }
+    sendTyped(
+        built,
+        'setAction:',
+        [FFIType.ptr],
+        FFIType.void,
+        selector('choose:'),
+    )
+    send(built, 'setTarget:', target)
+    sendTyped(built, 'setTag:', [FFIType.i64], FFIType.void, chosen.length)
+    chosen.push(item)
+    return built
+}
+
+/** A shortcut as AppKit spells it: the key, and the mask of the modifiers written before it. */
+function shortcut(key: string | undefined): {
+    keyEquivalent: string
+    modifiers: number
+} {
+    if (key === undefined || key === '')
+        return { keyEquivalent: '', modifiers: 0 }
+    const parts = key.toLowerCase().split('+')
+    const last = parts.pop() as string
+    let modifiers = 0
+    for (const part of parts) modifiers |= MODIFIERS[part] ?? 0
+    const named = NAMED_KEYS[last]
+    const function_ = /^f([1-9]|1[0-2])$/.exec(last)
+    const keyEquivalent =
+        named ??
+        (function_ === null
+            ? last
+            : String.fromCharCode(0xf704 + Number(function_[1]) - 1))
+    return { keyEquivalent, modifiers }
+}

package/src/server/negotiateEncoding.ts

@@ -0,0 +1,39 @@
+// 38.30 — WHICH OF THE ENCODINGS ON OFFER A REQUEST TAKES, or `undefined` for the bytes as they
+// are. What is on offer is asked rather than assumed: a request preferring brotli for a file with
+// only a gzip copy takes the gzip, where picking first and checking after would send it neither.
+//
+// The highest quality the request gives an encoding wins, a tie goes to the one offered first,
+// and `q=0` is a refusal rather than a low preference — so `br;q=0, *` is gzip and `*;q=0` is
+// nothing, which a parse that only looked for the token would get wrong both ways.
+
+import { ENCODING_SUFFIX } from './CLIENT_BUILD.ts'
+import { qualitiesOf } from './qualitiesOf.ts'
+
+export type Encoding = keyof typeof ENCODING_SUFFIX
+
+/**
+ * Every encoding, in `ENCODING_SUFFIX`'s order.
+ *
+ * What a document rendered per request can offer.
+ */
+export const ENCODINGS = Object.keys(ENCODING_SUFFIX) as Encoding[]
+
+/** The encoding on offer the request takes, or `undefined` for the bytes as they are. */
+export function negotiateEncoding(
+    accepted: string | null,
+    offered: readonly Encoding[],
+): Encoding | undefined {
+    if (accepted === null) return undefined
+    const qualities = qualitiesOf(accepted)
+    const wildcard = qualities.get('*') ?? 0
+    let chosen: Encoding | undefined
+    let best = 0
+    for (const encoding of offered) {
+        const quality = qualities.get(encoding) ?? wildcard
+        if (quality > best) {
+            best = quality
+            chosen = encoding
+        }
+    }
+    return chosen
+}

package/src/server/plainAnswer.ts

@@ -0,0 +1,19 @@
+/**
+ * A plain-text answer at `status`, never stored.
+ *
+ * 21.3 — A REFUSAL ABIDE ANSWERS AS TEXT, typed. `stamp` rebuilds an answer to give it a reason
+ * phrase (17.8), and a string body rebuilt goes out as `application/octet-stream`.
+ *
+ * 21.1 — `nosniff` HERE TOO, though `stamp` sets it on whatever an app answers: `abide dev`'s
+ * listener answers with this where no app stands behind it, and nothing stamps those.
+ */
+export function plainAnswer(message: string, status: number): Response {
+    return new Response(message, {
+        status,
+        headers: {
+            'content-type': 'text/plain; charset=utf-8',
+            'cache-control': 'private, no-store',
+            'x-content-type-options': 'nosniff',
+        },
+    })
+}

package/src/server/prefers.ts

@@ -0,0 +1,25 @@
+import { qualitiesOf } from './qualitiesOf.ts'
+
+/**
+ * Whether the request's `accept` header takes `wanted` over `over`.
+ *
+ * Listed at a higher quality, or at the same one and ahead of it. `wanted` has to be NAMED — a
+ * wildcard says nothing about which the reader prefers — and `wanted;q=0` is a refusal of it, not
+ * a low preference.
+ */
+export function prefers(
+    request: Request,
+    wanted: string,
+    over: string,
+): boolean {
+    const qualities = qualitiesOf(request.headers.get('accept') ?? '')
+    const wantedQuality = qualities.get(wanted) ?? 0
+    if (wantedQuality <= 0) return false
+    const overQuality = qualities.get(over) ?? 0
+    if (wantedQuality !== overQuality) return wantedQuality > overQuality
+    for (const token of qualities.keys()) {
+        if (token === wanted) return true
+        if (token === over) return false
+    }
+    return false
+}