Contents

Protocol

Custom URL scheme handlers (main process).

Use request.url with new URL(request.url).pathname (and search params if needed) to branch per resource under one scheme.

The following example registers the app scheme and shows one handler serving multiple resources: an HTML document at app://home/, JSON at app://api/config.json, and a 404 for any other path, using plain ProtocolResponse objects with different mimeType and statusCode values.

Example

import { protocol } from '@mobrowser/api';

protocol.handle('app', (request: Request) => {
  const path = new URL(request.url).pathname;
  if (path === '/home/') {
    return {
      statusCode: 200,
      mimeType: 'text/html',
      charset: 'utf-8',
      data: '<html><head><title>Home</title></head><body></body></html>',
    };
  }
  if (path === '/api/config.json') {
    return {
      statusCode: 200,
      mimeType: 'application/json',
      charset: 'utf-8',
      data: JSON.stringify({ theme: 'dark' }),
    };
  }
  return {
    statusCode: 404,
    mimeType: 'text/plain',
    charset: 'utf-8',
    data: 'Not found',
  };
});

Methods

handle()

handle(scheme: string, handler: (request: Request) => Response | Promise<Response> | ProtocolResponse | Promise<ProtocolResponse>): void;

Registers a handler for scheme. Pass the bare scheme name only: no : or :// (e.g. "app" for app://… URLs).

scheme must be a valid URL scheme token (WHATWG URL standard): the first character must be an ASCII letter (A–Z or a–z); each following character must be an ASCII letter, an ASCII digit, or one of +, -, .. Other characters, an empty string, or a first character that is not a letter cause a TypeError. Letter case is ignored for matching: the handler is registered under the same lowercase canonical form the URL parser uses, so Demo applies to navigation and fetch URLs that use demo:.

The handler is called for navigations and fetches whose URL uses this scheme after it was registered. The argument is a Fetch API Request object.

Return a Response (or a Promise of one), or a ProtocolResponse (or a Promise thereof), to supply status, headers, and body.

You cannot override the built-in mobrowser scheme (any letter case of mobrowser is rejected). You also cannot override standard URL schemes (those with the normal generic scheme://... form in the URL layer), such as http, https, file, ftp, ws, wss, and others that are already handled by the browser. Those loads use the ordinary network or internal pipeline; attempting to register those scheme names throws a TypeError.

Parameter	Type	Description
`scheme`	`string`	Bare scheme token; must satisfy URL scheme grammar, and must not name `mobrowser` or another standard URL scheme MoBrowser forbids overriding.
`handler`	(request: Request) => Response	Promise

removeHandler()

removeHandler(scheme: string): void;

Removes a handler for scheme.

Parameter	Type	Description
`scheme`	`string`	Bare scheme token; must satisfy URL scheme grammar, and must not name `mobrowser` or another standard URL scheme MoBrowser forbids overriding.