Custom URL schemes on macOS, Linux and Windows (story 8, Canvases 30–32)

[shannah]

Lets an application register its own URL scheme, such as aaf, before the first WebView exists. Every request to aaf://… is then answered by a Java handler, with no local HTTP server, port or token.

Built with SPDD:

• story requirements/[User-story-8]serve-pages-from-a-custom-url-scheme.md;
• analysis spdd/analysis/GGQPA-XXX-202609261430-[Analysis]-serve-pages-from-a-custom-url-scheme.md;
• Canvas 30: the Java API, the dispatcher, macOS and the demo;
• Canvas 31: Linux (WebKitGTK);
• Canvas 32: Windows (WebView2).

Java API (Canvas 30)

• WebViewSchemes — register(scheme, handler), isSupported() and registeredSchemes().
  • A scheme name is 2–32 characters: a letter first, then letters, digits, +, - or ..
  • The web's own schemes are refused.
  • Registration is refused once the first engine exists.
  • The capability check starts AWT before loading the native library. Without that, JDK 8 on macOS crashed in libawt_lwawt.
  • The refusal messages' non-ASCII characters are written as \u escapes, so the source compiles under javac's Cp1252 default on Windows.
• WebViewSchemeRequest, WebViewSchemeResponse, WebViewSchemeHandler and WebViewSchemeResponder.
• SchemeDispatcher:
  • runs handlers on webview-scheme-N daemon threads;
  • answers each request exactly once: 500 if the handler throws, 504 after 30 s, 404 for an unknown scheme, 413 for a request over 16 MB, 500 for a response over 64 MB;
  • drops Content-Length, adds a default Content-Type, and sets Access-Control-Allow-Origin to the request's own origin.

Native

• macOS: one WKURLSchemeHandler is installed on each engine's configuration, and popups inherit it.
• Linux (Canvas 31):
  • each scheme is registered once on WebKitGTK's default web context, as secure and CORS-enabled, and every view and popup shares that context. Both component modes are covered;
  • new optional loader symbols cover the request method, headers and body and the response status and headers. They are used where the engine has them and never fail the load. There is still no link-time WebKit, JavaScriptCore or libsoup dependency.
• Windows (Canvas 32):
  • the schemes are declared on the WebView2 environment through the SDK's own WRL helpers (secure, with a host, accepting requests from pages on the same scheme), so every other option keeps its SDK default;
  • with nothing registered, options stay null, as before;
  • a WebResourceRequested filter and handler go on the engine's webview and on every popup child;
  • each request is paused and completed on the engine thread with CreateWebResourceResponse.
• Linux and Windows never cancel an abandoned request: neither engine reports one, so the 30 s timeout ends it.

Tests and verification

• Java: WebViewSchemesTest, SchemeDispatcherTest and WebViewSchemeResponseTest. The full suite passes: 236 tests, 0 failures.
• The demo has an optional automatic mode, SCHEMEDEMO_AUTO=1. It runs 8 checks the page can observe and exits 0 only if all pass.
• macOS: the manual checklist passes.
• Linux: the automatic demo passes in both modes (WebKitGTK 2.52), and the demo also passed on the author's machine.
• Windows: the demo passes on the author's machine.
• CI compiles all six native targets.

Motivation: the Agentic App Framework will serve its local-database browser at aaf://db/ (webliteca/agentic-app-framework#378).

🤖 Generated with Claude Code

https://claude.ai/code/session_01EvuvnSZ2qxgNJkF4T5eD6V