tor-browser

MozCachedOHTTPProtocolHandler.sys.mjs (32430B)

---

/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

import { XPCOMUtils } from "resource://gre/modules/XPCOMUtils.sys.mjs";

const lazy = {};

ChromeUtils.defineESModuleGetters(lazy, {
 ObliviousHTTP: "resource://gre/modules/ObliviousHTTP.sys.mjs",
 E10SUtils: "resource://gre/modules/E10SUtils.sys.mjs",
 NetUtil: "resource://gre/modules/NetUtil.sys.mjs",
});

XPCOMUtils.defineLazyServiceGetter(
 lazy,
 "obliviousHttpService",
 "@mozilla.org/network/oblivious-http-service;1",
 Ci.nsIObliviousHttpService
);

/**
* For now, the configuration and relay we're using is the "common" one, but
* the prefs are stored in a newtab-specific way. In the future, it's possible
* that we'll have different OHTTP configurations and relays for different
* types of resource requests, so we map the moz-cached-ohttp host to relay and
* config prefs here.
*/
const HOST_MAP = new Map([
 [
   "newtab-image",
   {
     gatewayConfigURLPrefName:
       "browser.newtabpage.activity-stream.discoverystream.ohttp.configURL",
     relayURLPrefName:
       "browser.newtabpage.activity-stream.discoverystream.ohttp.relayURL",
   },
 ],
]);

/**
* 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.
*/
export class MozCachedOHTTPProtocolHandler {
 /**
  * The protocol scheme handled by this handler.
  */
 scheme = "moz-cached-ohttp";

 /**
  * Injectable OHTTP service for testing. If null, uses the default service.
  */
 #injectedOHTTPService = null;

 /**
  * Determines whether a given port is allowed for this protocol.
  *
  * @param {number} _port
  *   The port number to check.
  * @param {string} _scheme
  *   The protocol scheme.
  * @returns {boolean}
  *   Always false as this protocol doesn't use ports.
  */
 allowPort(_port, _scheme) {
   return false;
 }

 /**
  * Creates a new channel for handling moz-cached-ohttp:// URLs.
  *
  * @param {nsIURI} uri
  *   The URI to create a channel for.
  * @param {nsILoadInfo} loadInfo
  *   Load information containing security context.
  * @returns {MozCachedOHTTPChannel}
  *   A new channel instance.
  * @throws {Components.Exception}
  *   If the request is not from a valid context
  */
 newChannel(uri, loadInfo) {
   // Check if we're in a privileged about content process
   if (
     Services.appinfo.remoteType == lazy.E10SUtils.PRIVILEGEDABOUT_REMOTE_TYPE
   ) {
     return new MozCachedOHTTPChannel(
       uri,
       loadInfo,
       this,
       this.#getOHTTPService(),
       !!this.#injectedOHTTPService /* inTestingMode */
     );
   }

   // In main process, allow system principals and check loading principal's remote type
   if (Services.appinfo.processType == Services.appinfo.PROCESS_TYPE_DEFAULT) {
     const loadingPrincipal = loadInfo?.loadingPrincipal;
     if (loadingPrincipal) {
       // Allow system principals in parent process (for tests and internal usage)
       if (loadingPrincipal.isSystemPrincipal) {
         return new MozCachedOHTTPChannel(
           uri,
           loadInfo,
           this,
           this.#getOHTTPService(),
           !!this.#injectedOHTTPService /* inTestingMode */
         );
       }

       try {
         const remoteType =
           lazy.E10SUtils.getRemoteTypeForPrincipal(loadingPrincipal);
         if (remoteType === lazy.E10SUtils.PRIVILEGEDABOUT_REMOTE_TYPE) {
           return new MozCachedOHTTPChannel(
             uri,
             loadInfo,
             this,
             this.#getOHTTPService(),
             !!this.#injectedOHTTPService /* inTestingMode */
           );
         }
       } catch (e) {
         // E10SUtils might throw for invalid principals, fall through to rejection
       }
     }
   }

   throw Components.Exception(
     "moz-cached-ohttp protocol only accessible from privileged about content",
     Cr.NS_ERROR_INVALID_ARG
   );
 }

 /**
  * Gets both the gateway configuration and relay URI for making OHTTP
  * requests.
  *
  * @param {string} host
  *   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").
  * @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
  * @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.
  */
 async getOHTTPGatewayConfigAndRelayURI(host) {
   let hostMapping = HOST_MAP.get(host);
   if (!hostMapping) {
     throw new Error(`Unrecognized host for OHTTP config: ${host}`);
   }
   if (
     hostMapping.gatewayConfigURL === undefined ||
     hostMapping.relayURL === undefined
   ) {
     XPCOMUtils.defineLazyPreferenceGetter(
       hostMapping,
       "gatewayConfigURL",
       hostMapping.gatewayConfigURLPrefName,
       ""
     );
     XPCOMUtils.defineLazyPreferenceGetter(
       hostMapping,
       "relayURL",
       hostMapping.relayURLPrefName,
       ""
     );
   }
   if (!hostMapping.gatewayConfigURL) {
     throw new Error(
       `OHTTP Gateway config URL not configured for host: ${host}`
     );
   }
   if (!hostMapping.relayURL) {
     throw new Error(`OHTTP relay URL not configured for host: ${host}`);
   }

   const ohttpGatewayConfig = await lazy.ObliviousHTTP.getOHTTPConfig(
     hostMapping.gatewayConfigURL
   );

   return {
     ohttpGatewayConfig,
     relayURI: Services.io.newURI(hostMapping.relayURL),
   };
 }

 /**
  * Injects an OHTTP service for testing purposes.
  *
  * @param {nsIObliviousHttpService} service
  *   The service to inject, or null to use default.
  */
 injectOHTTPService(service) {
   this.#injectedOHTTPService = service;
 }

 /**
  * Gets the OHTTP service to use (injected or default).
  *
  * @returns {nsIObliviousHttpService}
  *   The OHTTP service to use.
  */
 #getOHTTPService() {
   return this.#injectedOHTTPService || lazy.obliviousHttpService;
 }

 QueryInterface = ChromeUtils.generateQI(["nsIProtocolHandler"]);
}

/**
* 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.
*/
export class MozCachedOHTTPChannel {
 #uri;
 #loadInfo;
 #protocolHandler;
 #ohttpService;
 #listener = null;
 #loadFlags = 0;
 #status = Cr.NS_OK;
 #cancelled = false;
 #originalURI;
 #contentType = "";
 #contentCharset = "";
 #contentLength = -1;
 #owner = null;
 #securityInfo = null;
 #notificationCallbacks = null;
 #loadGroup = null;
 #pendingChannel = null;
 #startedRequest = false;
 #inTestingMode = false;

 /**
  * Constructs a new MozCachedOHTTPChannel.
  *
  * @param {nsIURI} uri
  *   The moz-cached-ohttp:// URI to handle.
  * @param {nsILoadInfo} loadInfo
  *   Load information for the request with security context.
  * @param {MozCachedOHTTPProtocolHandler} protocolHandler
  *   The protocol handler instance that created this channel.
  * @param {nsIObliviousHttpService} ohttpService
  *   The OHTTP service to use.
  * @param {boolean} inTestingMode
  *   True if the channel is in a mode that makes it easier to stub and
  *   mock things out while under test.
  */
 constructor(
   uri,
   loadInfo,
   protocolHandler,
   ohttpService,
   inTestingMode = false
 ) {
   this.#uri = uri;
   this.#loadInfo = loadInfo;
   this.#protocolHandler = protocolHandler;
   this.#ohttpService = ohttpService;
   this.#originalURI = uri;
   this.#inTestingMode = inTestingMode;
 }

 /**
  * Gets the URI for this channel.
  *
  * @returns {nsIURI}
  *   The channel's URI.
  */
 get URI() {
   return this.#uri;
 }

 /**
  * Gets or sets the original URI for this channel.
  *
  * @type {nsIURI}
  */
 get originalURI() {
   return this.#originalURI;
 }

 set originalURI(aURI) {
   this.#originalURI = aURI;
 }

 /**
  * Gets the current status of the channel.
  *
  * @returns {number}
  *   The channel status (nsresult).
  */
 get status() {
   return this.#status;
 }

 /**
  * Gets or sets the content type of the loaded resource.
  *
  * @type {string}
  */
 get contentType() {
   return this.#contentType;
 }

 set contentType(aContentType) {
   this.#contentType = aContentType;
 }

 /**
  * Gets or sets the content charset of the loaded resource.
  *
  * @type {string}
  */
 get contentCharset() {
   return this.#contentCharset;
 }

 set contentCharset(aContentCharset) {
   this.#contentCharset = aContentCharset;
 }

 /**
  * Gets or sets the content length of the loaded resource.
  *
  * @type {number}
  *   The content length in bytes, or -1 if unknown.
  */
 get contentLength() {
   return this.#contentLength;
 }

 set contentLength(aContentLength) {
   this.#contentLength = aContentLength;
 }

 /**
  * Gets or sets the load flags for this channel.
  *
  * @type {number}
  */
 get loadFlags() {
   return this.#loadFlags;
 }

 set loadFlags(aLoadFlags) {
   this.#loadFlags = aLoadFlags;
 }

 /**
  * Gets or sets the load info for this channel.
  *
  * @type {nsILoadInfo}
  */
 get loadInfo() {
   return this.#loadInfo;
 }

 set loadInfo(aLoadInfo) {
   this.#loadInfo = aLoadInfo;
 }

 /**
  * Gets or sets the owner (principal) of this channel.
  *
  * @type {nsIPrincipal}
  */
 get owner() {
   return this.#owner;
 }

 set owner(aOwner) {
   this.#owner = aOwner;
 }

 /**
  * Gets the security info for this channel.
  *
  * @returns {nsITransportSecurityInfo}
  *   The security information for this channel.
  */
 get securityInfo() {
   return this.#securityInfo;
 }

 /**
  * Gets or sets the notification callbacks for this channel.
  *
  * @type {nsIInterfaceRequestor}
  */
 get notificationCallbacks() {
   return this.#notificationCallbacks;
 }

 set notificationCallbacks(aCallbacks) {
   this.#notificationCallbacks = aCallbacks;
 }

 /**
  * Gets or sets the load group for this channel.
  *
  * @type {nsILoadGroup}
  */
 get loadGroup() {
   return this.#loadGroup;
 }

 set loadGroup(aLoadGroup) {
   this.#loadGroup = aLoadGroup;
 }

 /**
  * Gets the name of this channel (its URI spec).
  *
  * @returns {string}
  *   The channel name.
  */
 get name() {
   return this.#uri.spec;
 }

 /**
  * Checks if this channel has a pending request.
  *
  * @returns {boolean}
  *   True if there is a pending request.
  */
 isPending() {
   return this.#pendingChannel ? this.#pendingChannel.isPending() : false;
 }

 /**
  * Cancels the channel with the given status.
  *
  * @param {number} status
  *   The status code to cancel with.
  */
 cancel(status) {
   this.#cancelled = true;
   this.#status = status;

   if (this.#pendingChannel) {
     this.#pendingChannel.cancel(status);
   }
 }

 /**
  * Suspends the channel if it has a pending request.
  */
 suspend() {
   if (this.#pendingChannel) {
     this.#pendingChannel.suspend();
   }
 }

 /**
  * Resumes the channel if it has a pending request.
  */
 resume() {
   if (this.#pendingChannel) {
     this.#pendingChannel.resume();
   }
 }

 /**
  * Opens the channel synchronously. Not supported for this protocol.
  *
  * @throws {Components.Exception}
  *   Always throws as sync open is not supported.
  */
 open() {
   throw Components.Exception(
     "moz-cached-ohttp protocol does not support synchronous open",
     Cr.NS_ERROR_NOT_IMPLEMENTED
   );
 }

 /**
  * Opens the channel asynchronously.
  *
  * @param {nsIStreamListener} listener
  *   The stream listener to notify.
  * @throws {Components.Exception}
  *   If the channel was already cancelled.
  */
 asyncOpen(listener) {
   if (this.#cancelled) {
     throw Components.Exception("Channel was cancelled", this.#status);
   }

   this.#listener = listener;

   this.#loadResource().catch(error => {
     console.error("moz-cached-ohttp channel error:", error);
     this.#notifyError(Cr.NS_ERROR_FAILURE);
   });
 }

 /**
  * Loads the requested resource using a cache-first strategy.
  * First attempts to load from HTTP cache, then falls back to OHTTP if not
  * cached.
  *
  * @returns {Promise<undefined>}
  *   Promise that resolves when loading is complete.
  */
 async #loadResource() {
   const { resourceURI, host } = this.#extractHostAndResourceURI();
   if (!resourceURI) {
     throw new Error("Invalid moz-cached-ohttp URL format");
   }

   // Try cache first (avoid network racing)
   const wasCached = await this.#tryCache(resourceURI);
   if (wasCached) {
     // Nothing to do - we'll be streaming the response from the cache.
     return;
   }

   // Fallback to OHTTP
   if (!HOST_MAP.has(host)) {
     throw new Error(`Unrecognized moz-cached-ohttp host: ${host}`);
   }

   await this.#loadViaOHTTP(resourceURI, host);
 }

 /**
  * Extracts both the host and target resource URL from the moz-cached-ohttp://
  * URL.
  *
  * Expected format: moz-cached-ohttp://newtab-image/?url=<encoded-https-url>
  *
  * @returns {{resourceURI: nsIURI, host: string}|null}
  *   Object containing extracted data, or null if invalid.
  *   Returns null if URL parsing fails, no 'url' parameter found,
  *   target URL is not HTTPS, or target URL is malformed.
  *   `resourceURI` is the decoded target image URI (HTTPS only).
  *   `host` is the moz-cached-ohttp host (e.g., "newtab-image").
  */
 #extractHostAndResourceURI() {
   try {
     const url = new URL(this.#uri.spec);
     const host = url.host;
     const searchParams = new URLSearchParams(url.search);
     const resourceURLString = searchParams.get("url");

     if (!resourceURLString) {
       return null;
     }

     // Validate that the extracted URL is a valid HTTP/HTTPS URL
     const resourceURL = new URL(resourceURLString);
     if (resourceURL.protocol !== "https:") {
       return null;
     }

     return { resourceURI: Services.io.newURI(resourceURLString), host };
   } catch (e) {
     return null;
   }
 }

 /**
  * Attempts to load the resource from the HTTP cache without making network
  * requests.
  *
  * @param {nsIURI} resourceURI
  *   The URI of the resource to load from cache
  * @returns {Promise<boolean>}
  *   Promise that resolves to true if loaded from cache
  */
 async #tryCache(resourceURI) {
   let result;

   // Bug 1977139: Transferring nsIInputStream currently causes crashes
   // from in-process child actors, so only use the MozCachedOHTTPChild
   // if we're running outside of the parent process. If we're running in the
   // parent process, we can just talk to the parent actor directly.
   if (
     Services.appinfo.processType === Services.appinfo.PROCESS_TYPE_DEFAULT
   ) {
     const [parentProcess] = ChromeUtils.getAllDOMProcesses();
     const parentActor = parentProcess.getActor("MozCachedOHTTP");
     result = await parentActor.tryCache(resourceURI);
   } else {
     const childActor = ChromeUtils.domProcessChild.getActor("MozCachedOHTTP");
     result = await childActor.sendQuery("tryCache", {
       uriString: resourceURI.spec,
     });
   }

   if (result.success) {
     // Stream from parent-provided inputStream
     const pump = this.#createInputStreamPump(result.inputStream);
     let headers = new Headers(result.headersObj);
     this.#applyContentHeaders(headers);

     await this.#streamFromCache(pump, result.inputStream);
     return true;
   }

   return false;
 }

 /**
  * Examines any response headers that were included with the cache entry or
  * network response, and sets any internal state to represent those headers.
  * For now, this is only the Content-Type header.
  *
  * @param {Headers} headers
  *   A Headers object that may have some header key value pairs included.
  */
 #applyContentHeaders(headers) {
   let contentTypeHeader = headers.get("Content-Type");
   if (contentTypeHeader) {
     let charSet = {};
     let hadCharSet = {};
     this.#contentType = Services.io.parseResponseContentType(
       contentTypeHeader,
       charSet,
       hadCharSet
     );

     if (hadCharSet.value) {
       this.#contentCharset = charSet.value;
     }
   }
 }

 /**
  * Creates an input stream pump for efficient data streaming.
  *
  * @param {nsIInputStream} inputStream
  *   The input stream to pump.
  * @returns {nsIInputStreamPump}
  *   The configured pump.
  */
 #createInputStreamPump(inputStream) {
   const pump = Cc["@mozilla.org/network/input-stream-pump;1"].createInstance(
     Ci.nsIInputStreamPump
   );
   pump.init(inputStream, 0, 0, false);
   return pump;
 }

 /**
  * Streams data from cache to the client listener.
  *
  * @param {nsIInputStreamPump} pump
  *   The input stream pump.
  * @param {nsIInputStream} inputStream
  *   The input stream for cleanup.
  * @returns {Promise<boolean>}
  *   Promise that resolves to true on success.
  */
 #streamFromCache(pump, inputStream) {
   return new Promise((resolve, reject) => {
     const listener = this.#createCacheStreamListener(
       pump,
       inputStream,
       resolve
     );

     try {
       pump.asyncRead(listener);
     } catch (error) {
       this.#safeCloseStream(inputStream);
       reject(error);
     }
   });
 }

 /**
  * Creates a stream listener for cache data streaming.
  *
  * @param {nsIInputStreamPump} pump
  *   The pump for channel tracking.
  * @param {nsIInputStream} inputStream
  *   Input stream for cleanup.
  * @param {Function} resolve
  *   Promise resolve function.
  * @returns {object}
  *   Stream listener implementation.
  */
 #createCacheStreamListener(pump, inputStream, resolve) {
   return {
     onStartRequest: () => {
       this.#startedRequest = true;
       this.#pendingChannel = pump;
       this.#listener.onStartRequest(this);
     },

     onDataAvailable: (request, innerInputStream, offset, count) => {
       this.#listener.onDataAvailable(this, innerInputStream, offset, count);
     },

     onStopRequest: (request, status) => {
       this.#pendingChannel = null;
       this.#safeCloseStream(inputStream);

       this.#listener.onStopRequest(this, status);
       resolve(Components.isSuccessCode(status));
     },
   };
 }

 /**
  * Safely closes an input stream, ignoring errors.
  *
  * @param {nsIInputStream} stream
  *   The stream to close.
  */
 #safeCloseStream(stream) {
   try {
     stream.close();
   } catch (e) {
     // Ignore close errors
   }
 }

 /**
  * Loads the resource via Oblivious HTTP when it's not available in cache.
  * Manually writes the response to the HTTP cache for future requests.
  *
  * @param {nsIURI} resourceURI
  *   The URI of the resource to load via OHTTP
  * @param {string} host
  *   A host matching one of the entries in HOST_MAP
  * @returns {Promise<void>} Promise that resolves when OHTTP loading is complete
  */
 async #loadViaOHTTP(resourceURI, host) {
   const { ohttpGatewayConfig, relayURI } =
     await this.#protocolHandler.getOHTTPGatewayConfigAndRelayURI(host);

   const ohttpChannel = this.#createOHTTPChannel(
     relayURI,
     resourceURI,
     ohttpGatewayConfig
   );

   return this.#executeOHTTPRequest(ohttpChannel);
 }

 /**
  * Creates and configures an OHTTP channel.
  *
  * @param {nsIURI} relayURI
  *   The OHTTP relay URI.
  * @param {nsIURI} resourceURI
  *   The target resource URI.
  * @param {Uint8Array} ohttpConfig
  *   The OHTTP configuration.
  * @returns {nsIChannel}
  *   The configured OHTTP channel.
  */
 #createOHTTPChannel(relayURI, resourceURI, ohttpConfig) {
   ChromeUtils.releaseAssert(
     Services.appinfo.processType === Services.appinfo.PROCESS_TYPE_DEFAULT ||
       Services.appinfo.remoteType ===
         lazy.E10SUtils.PRIVILEGEDABOUT_REMOTE_TYPE,
     "moz-cached-ohttp is only allowed in privileged content processes " +
       "or the main process"
   );

   const ohttpChannel = this.#ohttpService.newChannel(
     relayURI,
     resourceURI,
     ohttpConfig
   );

   // I'm not sure I love this, but in order for the privileged about content
   // process to make requests to the relay and not get dinged by
   // OpaqueResponseBlocking, we need to make the load come from the system
   // principal.
   const loadInfo = lazy.NetUtil.newChannel({
     uri: relayURI,
     loadUsingSystemPrincipal: true,
     contentPolicyType: Ci.nsIContentPolicy.TYPE_OTHER,
   }).loadInfo;

   // Copy relevant properties from our channel to the OHTTP channel
   ohttpChannel.loadInfo = loadInfo;
   ohttpChannel.loadFlags = this.#loadFlags | Ci.nsIRequest.LOAD_ANONYMOUS;

   if (this.#notificationCallbacks) {
     ohttpChannel.notificationCallbacks = this.#notificationCallbacks;
   }

   if (this.#loadGroup) {
     ohttpChannel.loadGroup = this.#loadGroup;
   }

   return ohttpChannel;
 }

 /**
  * Executes the OHTTP request with caching support.
  *
  * @param {nsIChannel} ohttpChannel
  *   The OHTTP channel to execute.
  * @returns {Promise<undefined, Error>}
  *   Promise that resolves when request is complete.
  */
 #executeOHTTPRequest(ohttpChannel) {
   this.#pendingChannel = ohttpChannel;

   let cachePipe = Cc["@mozilla.org/pipe;1"].createInstance(Ci.nsIPipe);
   cachePipe.init(
     true /* non-blocking input */,
     false /* blocking output */,
     0 /* segment size */,
     0 /* max segments */
   );
   let cacheStreamUpdate = new MessageChannel();

   return new Promise((resolve, reject) => {
     // Bug 1977139: Transferring nsIInputStream currently causes crashes
     // from in-process child actors, so only use the MozCachedOHTTPChild
     // if we're running outside of the parent process. If we're running in the
     // parent process, we can just talk to the parent actor directly.
     if (
       Services.appinfo.processType === Services.appinfo.PROCESS_TYPE_DEFAULT
     ) {
       const [parentProcess] = ChromeUtils.getAllDOMProcesses();
       const parentActor = parentProcess.getActor("MozCachedOHTTP");
       parentActor.writeCache(
         ohttpChannel.URI,
         cachePipe.inputStream,
         cacheStreamUpdate.port2
       );
     } else {
       const childActor =
         ChromeUtils.domProcessChild.getActor("MozCachedOHTTP");
       childActor.sendAsyncMessage(
         "writeCache",
         {
           uriString: ohttpChannel.URI.spec,
           cacheInputStream: cachePipe.inputStream,
           cacheStreamUpdatePort: cacheStreamUpdate.port2,
         },
         [cacheStreamUpdate.port2]
       );
     }

     const originalListener = this.#createOHTTPResponseListener(
       cacheStreamUpdate.port1,
       cachePipe.outputStream,
       resolve,
       reject
     );

     const finalListener = this.#setupStreamTee(
       originalListener,
       cachePipe.outputStream
     );

     try {
       ohttpChannel.asyncOpen(finalListener);
     } catch (error) {
       this.#cleanupCacheOnError(
         cacheStreamUpdate.port1,
         cachePipe.outputStream
       );
       reject(error);
     }
   });
 }

 /**
  * Creates a response listener for OHTTP requests with cache handling.
  *
  * @param {MessageChannelPort} cacheStreamUpdatePort
  *   MessagePort for sending cache control messages to the parent actor
  *   for operations like setting expiration time and dooming cache entries.
  * @param {nsIOutputStream} cachePipeOutputStream
  *   Output stream of the pipe used to send response data to the cache
  *   writer in the parent process via the JSActor.
  * @param {Function} resolve
  *   Promise resolve function.
  * @param {Function} reject
  *   Promise reject function.
  * @returns {nsIStreamListener}
  *   Stream listener implementation
  */
 #createOHTTPResponseListener(
   cacheStreamUpdatePort,
   cachePipeOutputStream,
   resolve,
   reject
 ) {
   return {
     onStartRequest: request => {
       // Copy content type from the OHTTP response to our channel
       if (request instanceof Ci.nsIHttpChannel) {
         try {
           const contentType = request.getResponseHeader("content-type");
           if (contentType) {
             let headers = new Headers();
             headers.set("content-type", contentType);
             this.#applyContentHeaders(headers);
           }
         } catch (e) {
           // Content-Type header not available
         }
       }

       this.#startedRequest = true;
       this.#listener.onStartRequest(this);
       this.#processResponseHeaders(cacheStreamUpdatePort, request);
       this.#processCacheControl(cacheStreamUpdatePort, request);
     },

     onDataAvailable: (request, inputStream, offset, count) => {
       this.#listener.onDataAvailable(this, inputStream, offset, count);
     },

     onStopRequest: (request, status) => {
       this.#pendingChannel = null;
       this.#finalizeCacheEntry(
         cacheStreamUpdatePort,
         cachePipeOutputStream,
         status
       );
       this.#listener.onStopRequest(this, status);

       if (Components.isSuccessCode(status)) {
         resolve();
       } else {
         reject(new Error(`OHTTP request failed with status: ${status}`));
       }
     },
   };
 }

 /**
  * Sets up stream tee for cache writing if cache output stream is available.
  *
  * @param {nsIStreamListener} originalListener
  *   The original stream listener.
  * @param {nsIOutputStream} cacheOutputStream
  *   Cache output stream (may be null).
  * @returns {nsIStreamListener}
  *   Final listener (tee or original).
  */
 #setupStreamTee(originalListener, cacheOutputStream) {
   if (!cacheOutputStream) {
     return originalListener;
   }

   try {
     const tee = Cc[
       "@mozilla.org/network/stream-listener-tee;1"
     ].createInstance(Ci.nsIStreamListenerTee);
     tee.init(originalListener, cacheOutputStream, null);
     return tee;
   } catch (error) {
     console.warn(
       "Failed to create stream tee, proceeding without caching:",
       error
     );
     this.#safeCloseStream(cacheOutputStream);
     return originalListener;
   }
 }

 /**
  * Finalizes cache entry after response completion.
  *
  * @param {MessageChannelPort} cacheStreamUpdatePort
  *   MessagePort for sending cache finalization messages to the parent actor.
  *   Used to doom the cache entry if the response failed.
  * @param {nsIOutputStream} cacheOutputStream
  *   Output stream to close.
  * @param {number} status
  *   Response status code.
  */
 #finalizeCacheEntry(cacheStreamUpdatePort, cacheOutputStream, status) {
   try {
     if (cacheOutputStream) {
       cacheOutputStream.closeWithStatus(Cr.NS_BASE_STREAM_CLOSED);
     }

     if (!Components.isSuccessCode(status)) {
       cacheStreamUpdatePort.postMessage({ name: "DoomCacheEntry" });
     }
   } catch (error) {
     console.warn("Failed to finalize cache entry:", error);
   }
 }

 /**
  * Cleans up cache resources on error.
  *
  * @param {MessageChannelPort} cacheStreamUpdatePort
  *   MessagePort for sending error cleanup messages to the parent actor.
  *   Used to doom the cache entry when an error occurs during the request.
  * @param {boolean} cacheOutputStream
  */
 #cleanupCacheOnError(cacheStreamUpdatePort, cacheOutputStream) {
   try {
     if (cacheOutputStream) {
       cacheOutputStream.closeWithStatus(Cr.NS_BASE_STREAM_CLOSED);
     }
     cacheStreamUpdatePort.postMessage({ name: "DoomCacheEntry" });
   } catch (e) {
     // Ignore cleanup errors
   }
 }

 /**
  * Notifies the listener of an error condition.
  *
  * @param {number} status
  *   The error status code.
  */
 #notifyError(status) {
   this.#status = status;
   if (this.#listener) {
     // Depending on when the error occurred, we may have already started
     // the request - but if not, start it.
     if (!this.#startedRequest) {
       this.#listener.onStartRequest(this);
     }
     this.#listener.onStopRequest(this, status);
   }
 }

 /**
  * Attempts to write the response headers into the cache entry.
  *
  * @param {MessageChannelPort} cacheStreamUpdatePort
  *   MessagePort for sending cache response headers to the parent actor.
  * @param {nsIHttpChannel} httpChannel
  *   The HTTP channel with response headers.
  */
 #processResponseHeaders(cacheStreamUpdatePort, httpChannel) {
   let headersObj = {};
   // nsIHttpChannel is marked as a builtinclass, meaning that it cannot
   // be implemented by script, which makes mocking out channels a pain. We
   // work around this by assuming that if we're in testing mode, that we've
   // been passed an nsIChannel implemented in JS that also happens to have a
   // visitResponseHeaders method implemented on it.
   if (this.#inTestingMode) {
     httpChannel = httpChannel.wrappedJSObject;
   } else if (!(httpChannel instanceof Ci.nsIHttpChannel)) {
     return;
   }

   httpChannel.visitResponseHeaders({
     visitHeader(name, value) {
       headersObj[name] = value;
     },
   });

   cacheStreamUpdatePort.postMessage({
     name: "WriteOriginalResponseHeaders",
     headersObj,
   });
 }

 /**
  * Sets appropriate cache expiration metadata based on response headers.
  *
  * @param {MessageChannelPort} cacheStreamUpdatePort
  *   MessagePort for sending cache metadata messages to the parent actor.
  *   Used to set cache expiration time and handle cache-control directives.
  * @param {nsIHttpChannel} httpChannel
  *   The HTTP channel with response headers.
  */
 #processCacheControl(cacheStreamUpdatePort, httpChannel) {
   if (!(httpChannel instanceof Ci.nsIHttpChannel)) {
     return;
   }

   let expirationTime = null;

   // Check for Cache-Control header first (takes precedence)
   let cacheControl = null;
   try {
     cacheControl = httpChannel.getResponseHeader("cache-control");
   } catch (e) {
     // Cache-Control header not available, continue to check Expires
   }

   if (cacheControl) {
     let cacheControlParseResult =
       Services.io.parseCacheControlHeader(cacheControl);
     // Respect max-age directive
     if (cacheControlParseResult.maxAge) {
       expirationTime = Date.now() + cacheControlParseResult.maxAge * 1000;
     } else if (
       cacheControlParseResult.noCache ||
       cacheControlParseResult.noStore
     ) {
       // Don't cache if explicitly prohibited
       cacheStreamUpdatePort.postMessage({ name: "DoomCacheEntry" });
       return;
     }
   }

   // Fallback to Expires header if Cache-Control max-age not found
   if (!expirationTime) {
     try {
       const expires = httpChannel.getResponseHeader("expires");
       if (expires) {
         expirationTime = new Date(expires).getTime();
       }
     } catch (e) {
       // Expires header not available
     }
   }

   // Set default expiration if no headers found (24 hours)
   expirationTime ??= Date.now() + 24 * 60 * 60 * 1000; // 24 hours

   // Set the expiration time in cache metadata
   cacheStreamUpdatePort.postMessage({
     name: "WriteCacheExpiry",
     expiry: Math.floor(expirationTime / 1000),
   });
 }

 QueryInterface = ChromeUtils.generateQI(["nsIChannel"]);
}