usage.rst (2268B)
1 ===================== 2 Developer Usage Guide 3 ===================== 4 5 This guide explains how developers can use the moz-cached-ohttp protocol in Firefox code. 6 7 Basic Usage 8 =========== 9 10 The moz-cached-ohttp protocol is designed to be used like any other resource loading mechanism in Firefox, 11 with the key differences being that it provides privacy-preserving OHTTP-based loading with automatic caching, 12 and cannot be used for regular content, so only privileged contexts can use the scheme. 13 14 Creating Resource Requests 15 ========================== 16 17 To load a resource via the moz-cached-ohttp protocol, construct a URL in the following format: 18 19 .. code-block:: javascript 20 21 const targetImageURL = "https://example.com/image.jpg"; 22 const encodedURL = encodeURIComponent(targetImageURL); 23 const ohttpImageURL = `moz-cached-ohttp://newtab-image/?url=${encodedURL}`; 24 25 **Important**: The host must be ``newtab-image`` - other hosts are not currently supported and will result in an error. 26 27 .. note:: 28 29 Target URLs must use the HTTPS protocol. HTTP URLs will be rejected. 30 31 Using with Image Elements 32 ------------------------- 33 34 The protocol can be used directly in HTML image elements within privileged contexts. 35 36 .. code-block:: html 37 38 <img src="moz-cached-ohttp://newtab-image/?url=https%3A%2F%2Fexample.com%2Fimage.jpg" /> 39 40 Using with Fetch API 41 --------------------- 42 43 In privileged contexts, you can use the Fetch API: 44 45 .. code-block:: javascript 46 47 try { 48 const response = await fetch(ohttpImageURL); 49 if (response.ok) { 50 const blob = await response.blob(); 51 // Use the image blob 52 } 53 } catch (error) { 54 console.error("Failed to load image:", error); 55 } 56 57 Performance Best Practices 58 =========================== 59 60 Cache Utilization 61 ------------------ 62 63 The protocol automatically handles caching, but you can optimize usage: 64 65 * **Consistent URLs**: Use the same encoded URL format for the same target resource 66 * **Have the server provide appropriate cache lifetimes**: The longer the lifetime, the less we may need to refetch the resource on the same client. 67 * **Respect cache headers**: Don't bypass cache unnecessarily with cache-busting parameters 68 * **Monitor cache hits**: In development, verify that repeated requests hit the cache