API

This page documents the API of the moz-cached-ohttp protocol implementation.

class MozCachedOHTTPProtocolHandler()

Protocol handler for the moz-cached-ohttp:// scheme. This handler enables loading resources over Oblivious HTTP (OHTTP) from privileged about: content processes, specifically for use for images in about:newtab. The handler implements a cache-first strategy to minimize OHTTP requests while providing fallback to OHTTP when resources are not available in the HTTP cache.

MozCachedOHTTPProtocolHandler.injectedOHTTPService

Injectable OHTTP service for testing. If null, uses the default service.

MozCachedOHTTPProtocolHandler.scheme

The protocol scheme handled by this handler.

MozCachedOHTTPProtocolHandler.allowPort(_port, _scheme)

Determines whether a given port is allowed for this protocol.

Arguments:

  • _port (number) – The port number to check.

  • _scheme (string) – The protocol scheme.

Returns:

boolean – Always false as this protocol doesn’t use ports.

MozCachedOHTTPProtocolHandler.getOHTTPGatewayConfigAndRelayURI(host)

Gets both the gateway configuration and relay URI for making OHTTP requests.

Arguments:

  • host (string) – A key for an entry in HOST_MAP that determines which OHTTP configuration and relay will be used for the request (e.g., “newtab-image”).

Throws:

Error – If the host is unrecognized, or if either the gateway config URL or relay URL preferences are not configured, or if fetching the gateway configuration fails.

Returns:

Promise.<{ohttpGatewayConfig: Uint8Array, relayURI: nsIURI}> – Promise that resolves to an object containing both OHTTP components:

Returns:

Uint8Array – returns.ohttpGatewayConfig The binary OHTTP gateway configuration

Returns:

nsIURI – returns.relayURI The nsIURI for the OHTTP relay endpoint

MozCachedOHTTPProtocolHandler.injectOHTTPService(service)

Injects an OHTTP service for testing purposes.

Arguments:

  • service (nsIObliviousHttpService) – The service to inject, or null to use default.

MozCachedOHTTPProtocolHandler.newChannel(uri, loadInfo)

Creates a new channel for handling moz-cached-ohttp:// URLs.

Arguments:

  • uri (nsIURI) – The URI to create a channel for.

  • loadInfo (nsILoadInfo) – Load information containing security context.

Throws:

Components.Exception – If the request is not from a valid context

Returns:

MozCachedOHTTPChannel – A new channel instance.

class MozCachedOHTTPChannel(uri, loadInfo, protocolHandler, ohttpService)

Channel implementation for moz-cached-ohttp:// URLs. This channel first attempts to load resources from the HTTP cache to avoid unnecessary OHTTP requests, and falls back to loading via OHTTP if the resource is not cached.

Constructs a new MozCachedOHTTPChannel.

Arguments:

  • uri (nsIURI) – The moz-cached-ohttp:// URI to handle.

  • loadInfo (nsILoadInfo) – Load information for the request with security context.

  • protocolHandler (MozCachedOHTTPProtocolHandler) – The protocol handler instance that created this channel.

  • ohttpService (nsIObliviousHttpService) – The OHTTP service to use.

MozCachedOHTTPChannel.MozCachedOHTTPChannel

Constructs a new MozCachedOHTTPChannel.

MozCachedOHTTPChannel.URI

Gets the URI for this channel.

MozCachedOHTTPChannel.contentLength

type: number

Gets or sets the content length of the loaded resource.

MozCachedOHTTPChannel.contentType

type: string

Gets or sets the content type of the loaded resource.

MozCachedOHTTPChannel.loadFlags

type: number

Gets or sets the load flags for this channel.

MozCachedOHTTPChannel.loadGroup

type: nsILoadGroup

Gets or sets the load group for this channel.

MozCachedOHTTPChannel.loadInfo

type: nsILoadInfo

Gets or sets the load info for this channel.

MozCachedOHTTPChannel.name

Gets the name of this channel (its URI spec).

MozCachedOHTTPChannel.notificationCallbacks

type: nsIInterfaceRequestor

Gets or sets the notification callbacks for this channel.

MozCachedOHTTPChannel.originalURI

type: nsIURI

Gets or sets the original URI for this channel.

MozCachedOHTTPChannel.owner

type: nsIPrincipal

Gets or sets the owner (principal) of this channel.

MozCachedOHTTPChannel.securityInfo

Gets the security info for this channel.

MozCachedOHTTPChannel.status

Gets the current status of the channel.

MozCachedOHTTPChannel.asyncOpen(listener)

Opens the channel asynchronously.

Arguments:

  • listener (nsIStreamListener) – The stream listener to notify.

Throws:

Components.Exception – If the channel was already cancelled.

MozCachedOHTTPChannel.cancel(status)

Cancels the channel with the given status.

Arguments:

  • status (number) – The status code to cancel with.

MozCachedOHTTPChannel.isPending()

Checks if this channel has a pending request.

Returns:

boolean – True if there is a pending request.

MozCachedOHTTPChannel.open()

Opens the channel synchronously. Not supported for this protocol.

Throws:

Components.Exception – Always throws as sync open is not supported.

MozCachedOHTTPChannel.resume()

Resumes the channel if it has a pending request.

MozCachedOHTTPChannel.suspend()

Suspends the channel if it has a pending request.

class MozCachedOHTTPParent()

Parent process JSActor for handling cache lookups for moz-cachged-ohttp protocol. This actor handles cache operations that require parent process privileges.

MozCachedOHTTPParent.tryCache(resourceURI)

Attempts to load the resource from the HTTP cache without making network requests. On cache miss, provides an output stream for writing to cache.

Arguments:

  • resourceURI (nsIURI) – The URI of the resource to load from cache

Returns:

Promise.<object> – Promise that resolves to result object with success flag and data

MozCachedOHTTPParent.writeCache(resourceURI, cacheInputStream, cacheStreamUpdatePort)

Writes resource data to the HTTP cache. Opens a cache entry for the specified URI and copies data from the input stream to the cache, handling cache control messages for expiration and entry management.

Arguments:

  • resourceURI (nsIURI) – The URI of the resource to cache

  • cacheInputStream (nsIInputStream) – Input stream containing the resource data to cache

  • cacheStreamUpdatePort (MessageChannelPort) – MessagePort for receiving cache control messages: - “DoomCacheEntry”: Remove cache entry (on error/no-cache) - “WriteCacheExpiry”: Set cache expiration time

Returns:

Promise.<undefined> – Promise that resolves when caching is complete