@mpfrontend/nx-plugin 0.0.0-stage → 1.0.0

package/templates/feature/screen/features/__feature__/api/__feature__.ts.template

@@ -0,0 +1,13 @@
+/**
+ * The request boundary of the feature. Bind a request to a generated contract adapter of the app; every
+ * call is cancellable and bounded in time, and nothing here decides authorization.
+ */
+export type __Feature__Request = (signal: AbortSignal) => Promise<void>;
+export const REQUEST_TIMEOUT_MS = 10000;
+
+export async function run__Feature__(
+  request: __Feature__Request,
+  signal: AbortSignal,
+): Promise<void> {
+  await request(AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]));
+}

package/templates/feature/screen/features/__feature__/hooks/use-__feature__.ts.template

@@ -0,0 +1,27 @@
+'use client';
+import { useEffect, useRef, useState } from 'react';
+import { run__Feature__, type __Feature__Request } from '../api/__feature__';
+import { next__Feature__Status, type __Feature__Status } from '../model/__feature__';
+import { is__Feature__Busy } from '../utils/__feature__';
+
+/** The feature state and its orchestration: start, cancel on unmount, and map the outcome. */
+export function use__Feature__(request: __Feature__Request | undefined) {
+  const [status, setStatus] = useState<__Feature__Status>('idle');
+  const active = useRef<AbortController | null>(null);
+  useEffect(() => () => active.current?.abort(), []);
+  async function start() {
+    if (!request || is__Feature__Busy(status)) return;
+    const controller = new AbortController();
+    active.current = controller;
+    setStatus((current) => next__Feature__Status(current, 'start'));
+    try {
+      await run__Feature__(request, controller.signal);
+      if (!controller.signal.aborted)
+        setStatus((current) => next__Feature__Status(current, 'succeed'));
+    } catch {
+      if (!controller.signal.aborted)
+        setStatus((current) => next__Feature__Status(current, 'fail'));
+    }
+  }
+  return { status, start, available: request !== undefined };
+}

package/templates/feature/screen/features/__feature__/index.ts.template

@@ -0,0 +1,3 @@
+// The public entry of the feature. Code outside the feature imports only from here.
+export { __Feature__Screen, type __Feature__ScreenProps } from './ui/__feature__-screen';
+export type { __Feature__Request } from './api/__feature__';

package/templates/feature/screen/features/__feature__/model/__feature__.test.ts.template

@@ -0,0 +1,12 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { next__Feature__Status } from './__feature__';
+
+test('a result is accepted only while the workflow is running', () => {
+  assert.equal(next__Feature__Status('idle', 'start'), 'running');
+  assert.equal(next__Feature__Status('running', 'succeed'), 'done');
+  assert.equal(next__Feature__Status('running', 'fail'), 'failed');
+  assert.equal(next__Feature__Status('failed', 'start'), 'running');
+  assert.equal(next__Feature__Status('idle', 'succeed'), 'idle');
+  assert.equal(next__Feature__Status('done', 'fail'), 'done');
+});

package/templates/feature/screen/features/__feature__/model/__feature__.ts.template

@@ -0,0 +1,12 @@
+/** The workflow states of the feature and the only transitions between them. */
+export type __Feature__Status = 'idle' | 'running' | 'done' | 'failed';
+export type __Feature__Event = 'start' | 'succeed' | 'fail';
+
+export function next__Feature__Status(
+  status: __Feature__Status,
+  event: __Feature__Event,
+): __Feature__Status {
+  if (event === 'start') return status === 'running' ? status : 'running';
+  if (status !== 'running') return status;
+  return event === 'succeed' ? 'done' : 'failed';
+}

package/templates/feature/screen/features/__feature__/ui/__feature__-panel.tsx.template

@@ -0,0 +1,22 @@
+'use client';
+import type { __Feature__Request } from '../api/__feature__';
+import { use__Feature__ } from '../hooks/use-__feature__';
+import { __Feature__View } from './__feature__-view';
+
+/**
+ * The panel binds the feature to its request. Until a request is bound to a generated contract adapter,
+ * the feature renders as not available rather than inventing an endpoint.
+ */
+const request: __Feature__Request | undefined = undefined;
+
+export function __Feature__Panel({ language }: { language: string }) {
+  const state = use__Feature__(request);
+  return (
+    <__Feature__View
+      status={state.status}
+      available={state.available}
+      language={language}
+      onStart={state.start}
+    />
+  );
+}

package/templates/feature/screen/features/__feature__/ui/__feature__-screen.tsx.template

@@ -0,0 +1,15 @@
+import { cookies } from 'next/headers';
+import { preferenceCookie, visitorLocale } from '../../../config/app';
+import { __Feature__Panel } from './__feature__-panel';
+
+export type __Feature__ScreenProps = Readonly<{
+  params?: Promise<Readonly<Record<string, string>>>;
+  searchParams?: Promise<Readonly<Record<string, string | string[] | undefined>>>;
+  basePath: string;
+}>;
+
+/** The screen of the feature: it resolves the visitor's locale on the server and renders the panel. */
+export async function __Feature__Screen(_props: __Feature__ScreenProps) {
+  const language = visitorLocale((await cookies()).get(preferenceCookie.name)?.value);
+  return <__Feature__Panel language={language} />;
+}

package/templates/feature/screen/features/__feature__/ui/__feature__-view.test.tsx.template

@@ -0,0 +1,25 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { __Feature__View } from './__feature__-view';
+
+const render = (props: Parameters<typeof __Feature__View>[0]) =>
+  renderToStaticMarkup(createElement(__Feature__View, props));
+
+test('an unbound feature is announced and cannot start', () => {
+  const html = render({ status: 'idle', available: false, language: 'en', onStart: () => {} });
+  assert.match(html, /aria-disabled="true"/);
+  assert.match(html, /role="status"/);
+});
+
+test('a running feature shows its busy state and a failure is an alert', () => {
+  assert.match(
+    render({ status: 'running', available: true, language: 'en', onStart: () => {} }),
+    /aria-busy="true"/,
+  );
+  assert.match(
+    render({ status: 'failed', available: true, language: 'en', onStart: () => {} }),
+    /role="alert"/,
+  );
+});

package/templates/feature/screen/features/__feature__/ui/__feature__-view.tsx.template

@@ -0,0 +1,38 @@
+import { PageFrame } from '@mpfrontend/app-layout';
+import { Button, Card } from '@mpfrontend/ui';
+import type { __Feature__Status } from '../model/__feature__';
+import { messages } from '../model/messages';
+
+type Props = Readonly<{
+  status: __Feature__Status;
+  available: boolean;
+  language: string;
+  onStart: () => void;
+}>;
+
+/** The view renders the state it is given and emits the start intent; it holds no workflow state. */
+export function __Feature__View({ status, available, language, onStart }: Props) {
+  const t = messages.translator(language);
+  const message = !available
+    ? t('unbound')
+    : status === 'done'
+      ? t('done')
+      : status === 'failed'
+        ? t('failed')
+        : '';
+  return (
+    <PageFrame title={t('title')}>
+      <Card>
+        <Button
+          onClick={onStart}
+          restricted={!available}
+          loading={status === 'running'}
+          loadingLabel={t('running')}
+        >
+          {t('run')}
+        </Button>
+        <p role={status === 'failed' ? 'alert' : 'status'}>{message}</p>
+      </Card>
+    </PageFrame>
+  );
+}

package/templates/feature/screen/features/__feature__/utils/__feature__.test.ts.template

@@ -0,0 +1,9 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { is__Feature__Busy } from './__feature__';
+
+test('only a running workflow is busy', () => {
+  assert.equal(is__Feature__Busy('running'), true);
+  for (const status of ['idle', 'done', 'failed'] as const)
+    assert.equal(is__Feature__Busy(status), false);
+});

package/templates/feature/screen/features/__feature__/utils/__feature__.ts.template

@@ -0,0 +1,6 @@
+import type { __Feature__Status } from '../model/__feature__';
+
+/** Whether the view should block a second start. */
+export function is__Feature__Busy(status: __Feature__Status): boolean {
+  return status === 'running';
+}

package/templates/next/README.md.template

@@ -0,0 +1,10 @@
+# __APP_NAME__
+
+Generated by the MP Frontend CLI. This app consumes packed platform packages and has no source alias into
+another repository. Product labels and behavior belong to authored overrides. The first slice is the
+public catalog: a list route and a detail route over one generated read. Protected writes, identity and
+retained realtime require their separate gates.
+
+See [docs/overview.md](docs/overview.md) for the routes and the layout, and
+[docs/api-contracts.md](docs/api-contracts.md) for the contracts. `.env.example` names the environment
+variables the app reads, without values.

package/templates/next/docs/api-contracts.md.template

@@ -0,0 +1,22 @@
+# API contracts
+
+- Captured contract: `contracts/openapi/presentation/__APP_NAME__/openapi.json`, an approved and
+  immutable OpenAPI input of this workspace.
+- Selection: `ftg.config.json` selects the operations this app uses. The `ftg-generate` target writes
+  `src/api/generated/catalog/`, and the `generated-check` target refuses drift.
+- Server boundary: `src/api/server/catalog.ts` sends the BFF only the parameters of the list protocol in
+  `src/entities/catalog/model/catalog-list.ts` and validates the response with the generated reader before a
+  feature sees it. The test beside the protocol checks it against the captured contract: a parameter that
+  `listCatalog` does not declare fails it.
+- Transfers: `src/app/api/transfer/[...path]/route.ts` relays the BFF's streamed routes under
+  `/__APP_NAME__/transfer/` (uploads and downloads, as streams) through `src/api/server/transfer.ts`. It
+  forwards only the session cookie named by `BFF_SESSION_COOKIE`, Origin, the CSRF token, the
+  idempotency key, Accept-Language and the content headers; the BFF's routes decide which paths, media
+  types and sizes exist.
+- Example read: the template reads `listCatalog`, which declares the query parameters `page`, `size` and
+  `search` and answers a paged response with `items`, `number`, `total`, `pageCount` and `hasMore`. Replace it
+  with an approved contract of this product, and its list protocol with the way that contract pages, sorts and
+  filters.
+
+Record each further operation here when `ftg.config.json` selects it: its operation id, the screens that
+use it and what the app assumes about it.

package/templates/next/docs/overview.md.template

@@ -0,0 +1,67 @@
+# __APP_NAME__
+
+The purpose of this app, its users and its terms belong at the top of this document. The sections below
+describe the structure that `mpfrontend create app` wrote.
+
+## Routes
+
+- `/` opens the catalog list (`src/app/page.tsx`).
+- `/catalog` is the catalog list screen; its page, size and search are URL state, read the same way on the
+  server for the first render and in the browser, so the screen can be linked and refreshed and back and
+  forward move through it (`src/app/catalog/page.tsx`). The browser reads further pages through the app's
+  own route `/api/catalog` (`src/app/api/catalog/route.ts`), under the access scope.
+- `/catalog/[position]` is the detail screen of one item, a child route of the list
+  (`src/app/catalog/[position]/page.tsx`).
+- `/components` shows the framework components (`src/app/components/page.tsx`).
+- `/api/access` answers the access snapshot of the visitor again when the window regains focus
+  (`src/app/api/access/route.ts`); `src/config/access.ts` defines it, and `src/app/providers.tsx` holds the app's
+  query client, its URL state adapter and its access provider.
+- `/api/transfer/...` relays the BFF's streamed routes for uploads and downloads
+  (`src/app/api/transfer/[...path]/route.ts`); see [api-contracts.md](api-contracts.md).
+
+## Layout
+
+- `src/app/` holds thin routes, the root layout and route handlers only.
+- `src/features/<feature>/` holds one user workflow: `ui/`, `model/`, `hooks/`, `api/`, `utils/` and its
+  `index.ts` public entry. Code outside a feature imports only that `index.ts`; lint refuses a deeper
+  import.
+- `src/entities/<entity>/` holds the types and rules that the features of one entity share.
+- `src/api/generated/` holds generated contracts; `src/api/server/` holds the hand-written server
+  boundary beside them.
+- `src/config/` holds validated configuration; `src/theme/` holds the theme registry.
+
+## Languages
+
+The app starts with English only (`en`, left to right, the default), and its `lang` and `dir` follow the
+locale registry in `src/config/app.ts`. To add a locale in this repository:
+
+1. Register it with its direction, `'<code>': { direction: 'ltr' }` or `'<code>': { direction: 'rtl' }`, and
+   a `numberingSystem` when its digits differ from the default.
+2. Add `messages/<code>.ts` next to `messages/en.ts` in every catalog set, typed
+   `Translation<typeof base>`, and list it in the `translations` of that set.
+3. Run the `catalog-check` target: it names every set that lacks the catalog or a key.
+
+To use another locale instead of English, register only that locale and make it `defaultLocale`, rename
+every `messages/en.ts` to `messages/<code>.ts` with the text of that locale, and set the base import and
+`defaultLocale` of every set to `<code>`. New features then start from that locale's catalog.
+
+Add a feature with `mpfrontend create feature`, a screen with `mpfrontend create route` and a package
+that two apps need with `mpfrontend create package`; see the CLI guide of MP Frontend.
+
+## Folders created when needed
+
+The generator does not create these empty; create each one with its first file, under this rule.
+
+| Location | Holds | Create it when |
+| --- | --- | --- |
+| `src/ui/` | Components shared by features of this app | A second feature needs a component that one feature holds; a component of one feature stays in its `ui/` |
+| `src/hooks/` | Domain-neutral React hooks reused by features of this app | A second feature needs a hook that carries no domain rule; a hook of one feature stays in its `hooks/` |
+| `src/utils/` | Domain-neutral pure helpers reused within this app | A second feature needs a helper without React, network or domain rule; a helper of one feature stays in its `utils/` |
+| `src/tests/` | Integration, contract, end-to-end and smoke tests, and their mock fixtures | The first test covers more than one feature or the app as a whole; a unit test stays beside the file it tests |
+| `public/` | Static assets this app owns | The app has its first static asset |
+| `docs/business-rules.md` | The rules and constraints of this app | The first business rule or constraint is agreed |
+| `docs/adr/` | Architecture decisions of this app, one file each | The first decision is taken that concerns this app only; a decision for every app goes in the workspace's `docs/` |
+| `infra/` (workspace root) | A local proxy example and the deployment templates of each app, without secrets | The workspace first needs a local proxy or a deployment template |
+
+Code that two apps need goes in a package (`mpfrontend create package`), never in one app's `src/`.
+The contracts this app reads are listed in [api-contracts.md](api-contracts.md).

package/templates/next/eslint.config.mjs.template

@@ -0,0 +1,4 @@
+import workspace from '../../eslint.config.mjs';
+
+// The workspace profile applies unchanged; app-specific additions go after it.
+export default [...workspace];

package/templates/next/ftg.config.json.template

@@ -0,0 +1,11 @@
+{
+  "openapi": "../../contracts/openapi/presentation/__APP_NAME__/openapi.json",
+  "output": "src/api/generated/catalog",
+  "resources": [
+    {
+      "name": "catalog",
+      "operationId": "listCatalog",
+      "responsePath": ["items"]
+    }
+  ]
+}

package/templates/next/next-env.d.ts.template

@@ -0,0 +1,2 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />

package/templates/next/next.config.mjs.template

@@ -0,0 +1,9 @@
+import { fileURLToPath } from 'node:url';
+/** @type {import('next').NextConfig} */
+const config = {
+  poweredByHeader: false,
+  reactStrictMode: true,
+  outputFileTracingRoot: fileURLToPath(new URL('../..', import.meta.url)),
+  serverExternalPackages: ['swagger-ui-dist'],
+};
+export default config;

package/templates/next/package.json.template

@@ -0,0 +1,27 @@
+{
+  "name": "@mpfrontend-reference/__APP_NAME__",
+  "version": "0.1.0-dev.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@mpfrontend/access-core": "1.0.0",
+    "@mpfrontend/access-react": "1.0.0",
+    "@mpfrontend/app-layout": "1.0.0",
+    "@mpfrontend/data-react": "1.0.0",
+    "@mpfrontend/ftg-core": "1.0.0",
+    "@mpfrontend/i18n": "1.0.0",
+    "@mpfrontend/presentation-server": "1.0.0",
+    "@mpfrontend/tokens": "1.0.0",
+    "@mpfrontend/ui": "1.0.0",
+    "@tailwindcss/postcss": "4.3.3",
+    "@tanstack/react-query": "5.104.0",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "next": "16.3.8",
+    "nuqs": "2.10.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "swagger-ui-dist": "5.29.5",
+    "tailwindcss": "4.3.3"
+  }
+}

package/templates/next/postcss.config.mjs.template

@@ -0,0 +1,2 @@
+// Tailwind CSS v4 compiles the utility classes of the app and of the MP Frontend UI components.
+export default { plugins: { '@tailwindcss/postcss': {} } };

package/templates/next/prepare-runtime.mjs.template

@@ -0,0 +1,11 @@
+import { copyFile, mkdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+const root = fileURLToPath(new URL('./', import.meta.url)),
+  require = createRequire(resolve(root, 'package.json'));
+const directory = resolve(root, 'runtime-assets/swagger');
+await mkdir(directory, { recursive: true });
+for (const file of ['swagger-ui.css', 'swagger-ui-bundle.js', 'swagger-ui-standalone-preset.js'])
+  await copyFile(require.resolve('swagger-ui-dist/' + file), resolve(directory, file));
+console.log('Prepared pinned Swagger runtime assets');

package/templates/next/project.json.template

@@ -0,0 +1,113 @@
+{
+  "name": "__APP_NAME__",
+  "projectType": "application",
+  "tags": ["scope:__APP_NAME__", "runtime:mixed", "type:app"],
+  "targets": {
+    "ftg-generate": {
+      "executor": "nx:run-commands",
+      "cache": true,
+      "inputs": [
+        "{workspaceRoot}/contracts/openapi/presentation/__APP_NAME__/openapi.json",
+        "{projectRoot}/ftg.config.json"
+      ],
+      "outputs": ["{projectRoot}/src/api/generated/catalog"],
+      "options": {
+        "command": "pnpm exec ftg generate --config apps/__APP_NAME__/ftg.config.json --json"
+      }
+    },
+    "generated-check": {
+      "executor": "nx:run-commands",
+      "cache": false,
+      "options": {
+        "command": "pnpm exec ftg check --config apps/__APP_NAME__/ftg.config.json --json"
+      }
+    },
+    "design-verify": {
+      "executor": "nx:run-commands",
+      "cache": false,
+      "options": {
+        "command": "pnpm exec mpfrontend design status --directory . --json"
+      }
+    },
+    "catalog-check": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "pnpm exec mpfrontend catalog check --app apps/__APP_NAME__ --json"
+      }
+    },
+    "format": {
+      "executor": "nx:run-commands",
+      "cache": false,
+      "options": {
+        "command": "pnpm exec prettier --write apps/__APP_NAME__"
+      }
+    },
+    "format:check": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "pnpm exec prettier --check apps/__APP_NAME__"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "pnpm exec eslint apps/__APP_NAME__"
+      }
+    },
+    "test": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "node --import tsx --test \"apps/__APP_NAME__/src/**/*.test.ts\" \"apps/__APP_NAME__/src/**/*.test.tsx\"",
+        "env": {
+          "TSX_TSCONFIG_PATH": "apps/__APP_NAME__/tsconfig.json"
+        }
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["^build", "ftg-generate", "runtime-assets"],
+      "outputs": ["{projectRoot}/.next", "{projectRoot}/runtime-assets"],
+      "options": {
+        "cwd": "apps/__APP_NAME__",
+        "command": "pnpm exec next build . --webpack"
+      }
+    },
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "pnpm exec tsc -p apps/__APP_NAME__/tsconfig.json --noEmit"
+      }
+    },
+    "runtime-assets": {
+      "executor": "nx:run-commands",
+      "cache": true,
+      "inputs": [
+        "{projectRoot}/prepare-runtime.mjs",
+        "{projectRoot}/package.json",
+        "{workspaceRoot}/pnpm-lock.yaml"
+      ],
+      "outputs": ["{projectRoot}/runtime-assets"],
+      "options": {
+        "command": "node apps/__APP_NAME__/prepare-runtime.mjs"
+      }
+    },
+    "dev": {
+      "dependsOn": ["runtime-assets"],
+      "executor": "nx:run-commands",
+      "cache": false,
+      "options": {
+        "cwd": "apps/__APP_NAME__",
+        "command": "pnpm exec next dev . --webpack -p 4301"
+      }
+    },
+    "start": {
+      "executor": "nx:run-commands",
+      "cache": false,
+      "options": {
+        "cwd": "apps/__APP_NAME__",
+        "command": "pnpm exec next start . -p 4301"
+      }
+    }
+  }
+}

package/templates/next/src/api/server/transfer.test.ts.template

@@ -0,0 +1,153 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  createServer,
+  type IncomingHttpHeaders,
+  type IncomingMessage,
+  type ServerResponse,
+} from 'node:http';
+import { createHash } from 'node:crypto';
+import { transferHandler } from './transfer';
+
+const MB = 1024 * 1024;
+const size = 8 * MB;
+const file = Buffer.alloc(size);
+for (let index = 0; index < size; index++) file[index] = index % 256;
+const digest = (bytes: Uint8Array) => createHash('sha256').update(bytes).digest('hex');
+const context = { params: Promise.resolve({ path: ['files', 'report'] }) };
+
+/** The promise's value, or a failure after `ms`: a streaming gate fails the test instead of hanging the run. */
+async function within<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new assert.AssertionError({ message })), ms);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** A fake BFF on a loopback port, so that the relay is tested without a backend. */
+async function fakeBff(handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>) {
+  const server = createServer((req, res) => {
+    handle(req, res).catch(() => res.destroy());
+  });
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address() as { port: number };
+  return {
+    origin: 'http://127.0.0.1:' + port,
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.closeAllConnections();
+        server.close(() => resolve());
+      }),
+  };
+}
+
+test('a file of several megabytes goes to the BFF and back through the relay, as streams', { timeout: 60000 }, async () => {
+  let seen: IncomingHttpHeaders = {};
+  const received: Buffer[] = [];
+  let reportArrival = () => {};
+  const arrived = new Promise<void>((resolve) => {
+    reportArrival = resolve;
+  });
+  const bff = await fakeBff(async (req, res) => {
+    if (req.method === 'GET') {
+      res.writeHead(200, {
+        'content-type': 'application/octet-stream',
+        'content-length': String(size),
+        'x-internal': 'not passed',
+      });
+      res.end(file);
+      return;
+    }
+    seen = req.headers;
+    for await (const chunk of req) {
+      received.push(chunk as Buffer);
+      reportArrival();
+    }
+    res.writeHead(201, { 'content-type': 'application/json', 'set-cookie': 'tracker=1' });
+    res.end('{"stored":true}');
+  });
+  try {
+    const handle = transferHandler(() => ({
+      bffOrigin: bff.origin,
+      basePath: '/app/transfer',
+      sessionCookie: 'app_session',
+    }));
+    // The client produces 1 MiB, then waits until the BFF has bytes: a relay that held the whole body
+    // would never let the upload finish.
+    let offset = 0;
+    const body = new ReadableStream<Uint8Array>(
+      {
+        async pull(controller) {
+          if (offset === MB)
+            await within(arrived, 10000, 'the BFF received no byte before the relay had the whole file');
+          if (offset >= size) {
+            controller.close();
+            return;
+          }
+          const chunk = file.subarray(offset, offset + 65536);
+          offset += chunk.length;
+          controller.enqueue(new Uint8Array(chunk));
+        },
+      },
+      { highWaterMark: 0 },
+    );
+    const upload = {
+      method: 'PUT',
+      body,
+      duplex: 'half',
+      headers: {
+        cookie: 'theme=dark; app_session=opaque',
+        origin: 'http://localhost',
+        'x-csrf-token': 'token',
+        'content-type': 'application/octet-stream',
+        'content-length': String(size),
+        authorization: 'Bearer not-forwarded',
+      },
+    };
+    const uploaded = await within(
+      handle(new Request('http://localhost/api/transfer/files/report', upload as RequestInit), context),
+      30000,
+      'the upload did not finish',
+    );
+    assert.equal(uploaded.status, 201);
+    assert.equal(digest(Buffer.concat(received)), digest(file));
+    assert.equal(seen.cookie, 'app_session=opaque');
+    assert.equal(seen['x-csrf-token'], 'token');
+    assert.equal(seen.authorization, undefined);
+    assert.deepEqual(uploaded.headers.getSetCookie(), []);
+    const downloaded = await within(
+      handle(
+        new Request('http://localhost/api/transfer/files/report', {
+          headers: { cookie: 'app_session=opaque' },
+        }),
+        context,
+      ),
+      10000,
+      'the download did not start',
+    );
+    assert.equal(downloaded.status, 200);
+    const bytes = await within(downloaded.arrayBuffer(), 30000, 'the download did not finish');
+    assert.equal(digest(new Uint8Array(bytes)), digest(file));
+    assert.equal(downloaded.headers.get('content-length'), String(size));
+    assert.equal(downloaded.headers.get('x-internal'), null);
+  } finally {
+    await bff.close();
+  }
+});
+
+test('without a session cookie name the relay is not configured', async () => {
+  const handle = transferHandler(() => ({
+    bffOrigin: 'http://127.0.0.1:9',
+    basePath: '/app/transfer',
+    sessionCookie: '',
+  }));
+  const response = await handle(new Request('http://localhost/api/transfer/files/report'), context);
+  assert.equal(response.status, 503);
+});