61 lines
2.0 KiB
Markdown
61 lines
2.0 KiB
Markdown
# Developer Usage Guide
|
|
|
|
This guide explains how developers can use the moz-cached-ohttp protocol in Firefox code.
|
|
|
|
## Basic Usage
|
|
|
|
The moz-cached-ohttp protocol is designed to be used like any other resource loading mechanism in Firefox,
|
|
with the key differences being that it provides privacy-preserving OHTTP-based loading with automatic caching,
|
|
and cannot be used for regular content, so only privileged contexts can use the scheme.
|
|
|
|
## Creating Resource Requests
|
|
|
|
To load a resource via the moz-cached-ohttp protocol, construct a URL in the following format:
|
|
|
|
```javascript
|
|
const targetImageURL = "https://example.com/image.jpg";
|
|
const encodedURL = encodeURIComponent(targetImageURL);
|
|
const ohttpImageURL = `moz-cached-ohttp://newtab-image/?url=${encodedURL}`;
|
|
```
|
|
|
|
**Important**: The host must be `newtab-image` - other hosts are not currently supported and will result in an error.
|
|
|
|
:::{note}
|
|
Target URLs must use the HTTPS protocol. HTTP URLs will be rejected.
|
|
:::
|
|
|
|
### Using with Image Elements
|
|
|
|
The protocol can be used directly in HTML image elements within privileged contexts.
|
|
|
|
```html
|
|
<img src="moz-cached-ohttp://newtab-image/?url=https%3A%2F%2Fexample.com%2Fimage.jpg" />
|
|
```
|
|
|
|
### Using with Fetch API
|
|
|
|
In privileged contexts, you can use the Fetch API:
|
|
|
|
```javascript
|
|
try {
|
|
const response = await fetch(ohttpImageURL);
|
|
if (response.ok) {
|
|
const blob = await response.blob();
|
|
// Use the image blob
|
|
}
|
|
} catch (error) {
|
|
console.error("Failed to load image:", error);
|
|
}
|
|
```
|
|
|
|
## Performance Best Practices
|
|
|
|
### Cache Utilization
|
|
|
|
The protocol automatically handles caching, but you can optimize usage:
|
|
|
|
- **Consistent URLs**: Use the same encoded URL format for the same target resource
|
|
- **Have the server provide appropriate cache lifetimes**: The longer the lifetime, the less we may need to refetch the resource on the same client.
|
|
- **Respect cache headers**: Don't bypass cache unnecessarily with cache-busting parameters
|
|
- **Monitor cache hits**: In development, verify that repeated requests hit the cache
|