Cache Media-Heavy Localhost Previews Safely

Understand the preview architecture before adding a cache

A typical remote preview begins with an application listening on a local IP address and port. The Localtonet client runs on a device that can reach that application, establishes an outbound connection to one of our relay servers, and gives the HTTP tunnel a public URL. A reviewer requests that URL, and the request reaches the local web service through the tunnel. This removes the need for inbound router port forwarding, a public IP address, VPN setup, or direct firewall changes.

That route does not automatically determine whether a browser, reverse proxy, or CDN may store the response. HTTP caching is controlled primarily by the response headers emitted by the application or by a caching layer that has been deliberately placed in front of it. Localtonet should therefore be treated as the public transport path in this design, not as an implicit media cache.

This separation of responsibilities is important. If a stale image appears, investigate the origin's URL and headers, the browser cache, and any separately configured shared cache. Do not assume the tunnel transformed the asset. Likewise, adding a public tunnel does not make an application response safe to cache. Authorization, tenant isolation, cookies, content sensitivity, and update behavior still belong to the application architecture.

Caching helps most when the same large, unchanged object is requested more than once. A video replayed during review, a font used on every page, or a stable image opened by several reviewers can be good candidates. A server-rendered HTML document, a live API response, or an image being edited every few minutes usually needs a more conservative policy.

Classify every response by sensitivity and mutability

Safe caching starts with classification, not with a list of file extensions. An extension can suggest content type, but it does not establish whether the response is public, personalized, or stable. Two JPEG responses can require opposite policies: a public fingerprinted background image may be safely reusable for a long time, while a temporary account document rendered as a JPEG should not enter a shared cache.

For every route family, answer four questions. Does the representation contain user-specific or confidential data? Can two authorized users receive different bytes from the same URL? How quickly can the content change? Does the URL change when the bytes change? Those answers define the appropriate cache behavior more reliably than asset size alone.

A practical default is to allow aggressive caching only when content-derived or build-derived names make the URL immutable. Keep documents, HTML, API output, authenticated media, and frequently edited assets conservative. Expand the cacheable set route by route after verifying that each cache key uniquely identifies the response.

Do not assume that a query parameter automatically creates a new cache identity in every intermediary. HTTP caches commonly incorporate the URI, including its query component, but a separately configured cache can normalize, ignore, or selectively include query parameters. If revision identity matters, a filename or path containing a content hash is usually easier to reason about than an undocumented cache-key rule.

Build a standards-based cache header policy

The Cache-Control response header communicates whether a response can be stored and how it may be reused. Validators such as ETag and Last-Modified let a client ask whether a stored representation is still current. These mechanisms solve related but distinct problems: freshness can avoid a network request, while validation can make the request inexpensive when the content has not changed.

Use no-store when storage itself is undesirable

Cache-Control: no-store tells caches not to store the response. It is an appropriate conservative policy for sensitive previews, authenticated HTML, private documents, debugging output, and routes whose stored content could cause confusion or disclosure. It is also useful when a developer must guarantee that each request reaches the application during a diagnostic session.

Cache-Control: no-store

This directive trades speed for predictability and privacy. It should not be applied indiscriminately to large public assets if repeated transfer is the problem being solved, but it is a sound default when the team has not yet established whether a response is shareable.

Use no-cache when storage is acceptable but reuse requires validation

Despite its name, no-cache does not mean that a cache may never store the response. It means the stored response must be validated with the origin before reuse. If the origin determines that the representation has not changed, it can answer with 304 Not Modified instead of retransmitting the body.

Cache-Control: no-cache
ETag: "revision-identifier"

This is often useful for mutable, non-sensitive media. Reviewers see updates promptly because every reuse is checked, while unchanged assets can avoid another full body transfer. The validator must change whenever the representation changes. A constant, weakly generated, or incorrectly reused ETag can hide an update just as effectively as an excessive freshness lifetime.

Use long-lived public caching only with immutable URLs

A fingerprinted URL binds an asset location to a specific revision. For example, an export process might generate a name containing a content hash. When the file changes, the process emits a different URL, and existing documents begin referencing that new location. The old object can remain cached because it still correctly represents the old URL.

Cache-Control: public, max-age=31536000, immutable

The one-year value above is an example policy, not a universal requirement. Choose a lifetime that fits the preview workflow. The essential condition is that bytes at the URL never change. If a development process overwrites an existing fingerprinted file, the URL is no longer immutable and the policy becomes unsafe.

Separate browser freshness from shared-cache freshness where necessary

max-age applies freshness to caches generally. s-maxage can set a different freshness lifetime for shared caches. This can be useful when a browser should revalidate relatively soon but an explicitly configured shared cache may retain a public object longer.

Cache-Control: public, max-age=60, s-maxage=600

Only use a shared-cache lifetime when the response really is safe for multiple users. A longer shared lifetime does not become safe merely because the content is large. Confidentiality and representation identity remain the primary constraints.

Choose and test validators carefully

An ETag is an opaque representation identifier selected by the origin. A strong ETag indicates byte-for-byte identity, while a weak ETag indicates semantic equivalence without guaranteeing identical bytes. Strong validation is often easier to reason about for downloadable media and range operations, provided the application can produce the identifier correctly.

Last-Modified uses a timestamp and can be simpler for file-backed assets, but timestamp precision and deployment behavior may not distinguish rapid edits. An ETag based on the actual representation or a trustworthy revision identifier can be more precise. An application may send both, but it must implement conditional request precedence correctly rather than treating them as unrelated switches.

Use Vary only for real representation dimensions

If the same URL returns different representations based on a request header, the cache must know which header contributes to identity. Vary: Accept-Encoding is common when compressed and uncompressed forms differ. Content negotiation can also involve headers such as Accept.

Avoid broad or accidental variation. A response that varies on volatile headers can produce many cache entries and little reuse. More importantly, Vary is not a replacement for access control. If authentication or tenant identity changes the body, a public shared cache is usually the wrong design.

Protect authenticated, personalized, and sensitive media

The most serious cache failure is not staleness. It is serving one user's private representation to another user. This can happen when an intermediary stores an authenticated response under a cache key that lacks the authorization context, tenant identity, or other input that changed the body.

For remote development previews, begin with Cache-Control: private, no-store on authenticated or personalized routes. The private directive prevents storage by shared caches, while no-store prevents storage generally. Using both makes the intent explicit when sensitive content should not persist in either shared or private caches.

Cache-Control: private, no-store

Do not solve authorization-specific variation by adding raw session identifiers, access tokens, or signed credentials to a cache key. That can leak secrets into logs and storage while still leaving subtle isolation errors. A safer design is to avoid shared caching for those responses. If an advanced private-media system genuinely requires shared caching, it needs a separately reviewed architecture with strict key isolation, controlled lifetimes, authorization-aware purge behavior, and protection against cache deception and poisoning. That is beyond a simple localhost preview.

Signed media URLs also require care. A URL containing an expiring signature may be different for each viewer or session. A shared cache could retain the body beyond the authorization window unless response policy and cache behavior are aligned. Treat such content as private by default instead of assuming that an expiring query string automatically prevents unsafe reuse.

Cookies deserve similar attention. If a response sets a session cookie or its contents depend on a cookie, do not make it publicly cacheable without a well-understood application design. A cache rule that ignores cookies may improve hit rates while serving the wrong representation. A rule that varies on an entire cookie header may fragment the cache and accidentally retain secrets. The simple, safe preview policy is to bypass shared caching whenever authentication or personalization participates in the response.

Keep the Localtonet device authentication token secret as well. It identifies the client device that runs the tunnel and should never be placed in source code, public HTML, screenshots, logs intended for reviewers, or cache keys. The same rule applies to application credentials and private endpoints.

Choose between browser, reverse-proxy, and CDN caching

Not every preview needs an additional shared cache. Browser caching is the smallest and safest place to start because it primarily benefits repeated requests by the same reviewer. A reverse proxy can centralize policy near the application. A CDN can place public objects closer to distributed reviewers, but it also introduces another storage and invalidation boundary.

A local reverse proxy can reduce repeated rendering or file reads, but it does not necessarily solve a constrained internet uplink. If that proxy runs on the same device behind the Localtonet tunnel, each response still leaves the device. A cache operating on remote infrastructure can avoid repeated origin transfer after a successful fill, but that behavior belongs to the separately selected cache provider and configuration. We do not present vendor-specific edge integration steps here because they are not part of the documented Localtonet HTTP tunnel workflow supplied for this guide.

Start with browser caching and validators. Add a shared layer only after there is evidence that multiple viewers repeatedly fetch the same public assets and that the local upload path is the limiting factor. This incremental approach reduces complexity and makes it easier to identify which layer produced a stale response.

Account for byte-range requests

Video, audio, and large documents may use the HTTP Range request header to retrieve only part of a representation. A supporting origin may return 206 Partial Content with a valid Content-Range header. Seeking within a video or audio track can generate multiple range requests.

Do not assume that every shared cache handles partial responses identically. Some caches store a complete object and serve ranges from it, some cache partial representations under specific conditions, and some bypass them. Confirm the chosen cache's documented behavior and test seeking, resumed downloads, and boundary ranges. A cache key must not confuse a partial response with a complete representation.

Compression also matters. Already compressed formats such as many video, audio, and image files often gain little from transport compression. HTML, JSON, SVG, and text assets may benefit. Whatever compression strategy is used, validators and Vary behavior must consistently identify the transferred representation.

Implement a cache policy without hiding development bugs

Implement the policy in stages. First inventory route families. Then set explicit origin headers. Next make immutable URLs genuinely immutable. Finally, introduce any shared cache as an independent component with a bypass option. This order keeps the application authoritative and allows the same response semantics to work through the local URL and the Localtonet public URL.

Plan invalidation before the first shared cache fill

There are three reliable ways to prevent an old public object from lingering. The preferred approach for immutable assets is URL versioning: publish the replacement at a new URL and update references. For mutable URLs, use a short freshness lifetime plus validation. If a shared cache must be purged immediately, use that provider's documented invalidation mechanism and verify the result. No universal purge command exists across reverse proxies and CDNs.

Purge is operationally useful but should not be the only correctness mechanism. A failed or delayed purge can leave reviewers with stale content. Versioned URLs make the desired revision part of the request identity and are easier to reason about across browser and shared-cache boundaries.

Keep negative responses short-lived or uncacheable

During development, avoid intentionally caching 404, 401, 403, and 500 responses. A missing file may appear seconds later after a build completes. An authorization failure may be repaired by a configuration change. A cached error can make the fix appear ineffective and prolong debugging.

Also ensure that fallback routing does not return HTML with a successful status for a missing media URL. If a request for a video receives the application shell, a cache may store the wrong content type under the media URL. Correct status codes and content types are part of cache correctness.

Expose the verified local origin with a Localtonet HTTP tunnel

Once the origin behaves correctly on the local network, add remote access as a distinct step. The Localtonet client must run on a device that can reach the service. The local target can be on that same device or at another local IP address reachable from it. The selected tunnel remains available only while the client is connected and the tunnel is running.

The current dashboard supplies device tokens and available relay server or region choices. Do not copy a token into this article, source control, a public terminal recording, or a message to reviewers. Available server codes and plan-dependent options must be obtained from the current product rather than hardcoded.

For current dashboard details, consult our Localtonet HTTP tunnel documentation. The tunnel should target the component that owns the final origin-facing behavior. If a local reverse proxy is responsible for cache headers or routing, point the tunnel at that proxy. If the application emits the final headers directly, point it at the application.

Verify cold loads, warm loads, validation, and access boundaries

Cache testing should establish where a response came from and whether its reuse was permitted. Start with the local origin, then test through the Localtonet URL, and finally test through any separately configured shared cache. Comparing those stages prevents a cache-layer issue from being mistaken for tunnel behavior.

Inspect response headers

Replace the placeholders below with the actual local address and public URL. These commands display response headers without embedding credentials:

curl -I http://127.0.0.1:PORT/path/to/public-media
curl -I https://PUBLIC-URL/path/to/public-media

Check Cache-Control, ETag, Last-Modified, Vary, Content-Type, Content-Length, and any cookies. Header-only requests use HEAD, and an application should make its metadata consistent with the corresponding GET. If the framework handles HEAD differently, confirm behavior with a normal GET while discarding the body:

curl -sS -D - -o /dev/null https://PUBLIC-URL/path/to/public-media

Test ETag validation

Copy the ETag returned by the first request and send it back in If-None-Match. The placeholder is intentionally not a real asset validator:

curl -sS -D - -o /dev/null \
  -H 'If-None-Match: "ETAG-FROM-FIRST-RESPONSE"' \
  https://PUBLIC-URL/path/to/public-media

An unchanged representation should normally produce 304 Not Modified without the media body. Edit or regenerate the asset and repeat the request. The validator should change, and the server should return the updated representation. This second part catches the common bug where an ETag remains constant after a file update.

Test a byte range

curl -sS -D - -o /dev/null \
  -H 'Range: bytes=0-1023' \
  https://PUBLIC-URL/path/to/video

If the origin supports ranges for that resource, inspect the response for an appropriate partial-content status and a valid Content-Range. Then use a browser to seek near the beginning, middle, and end of the media. Command-line checks verify protocol basics, while actual playback catches player and buffering behavior.

Run a cache correctness matrix

Browser developer tools can help distinguish transferred bytes from resources reused locally, but use a fresh profile or a clearly controlled cache setting for cold tests. Service workers add another cache layer and can override expectations even when HTTP headers look correct. If the application has a service worker, inspect its fetch and storage behavior separately.

Avoid treating a single fast reload as proof of correct caching. It may reflect an in-memory browser cache, a service worker, a speculative preload, or a shared cache. Correctness requires verifying the response headers, status codes, update behavior, and authorization boundaries.

Troubleshoot stale content and slow media systematically

The asset stays stale after an edit

Inspect the requested URL first. If it is advertised as immutable but the file was overwritten, publish a new fingerprinted URL. If the URL is intentionally mutable, inspect its freshness lifetime and validator. Confirm that the ETag or Last-Modified value changes when appropriate. Then check each possible storage layer: service worker, browser, local proxy, remote cache, and origin.

Do not add random query strings as the permanent fix. They may create unbounded cache entries, may be ignored by an intermediary's cache key, and do not correct the underlying versioning policy.

The same asset downloads in full on every request

Check whether the response says no-store, lacks a freshness policy, or lacks a validator. Confirm that the request method is cacheable and that authorization or cookies are not causing a deliberate bypass. Look for changing query parameters or response headers that produce a different cache key on every request.

If validation occurs but still returns a full response, verify that the client sends If-None-Match or If-Modified-Since and that the server recognizes it. A changing ETag on identical bytes also defeats validation.

Private media appears for the wrong reviewer

Treat this as a security incident, not a tuning problem. Disable or bypass the shared cache, stop the public tunnel if needed, and remove access to the affected route. Review authorization at the origin, cache keys, cookie handling, response directives, and any stored objects. Purge affected content using the cache provider's documented controls, but remember that browser copies cannot always be centrally removed.

Video starts but seeking fails

Inspect requests for Range and responses for 206 Partial Content, Content-Range, and a sensible Content-Length. Test the origin directly and through every layer. If local seeking works but remote seeking fails only after adding a cache, review that cache's documented partial-content behavior. Also verify that the application is not returning compressed or transformed bytes with metadata that describes a different representation.

The first load is still slow

A cache cannot serve an object it does not yet have. The first request may still be constrained by local generation time, disk reads, media size, and the developer's upload path. Optimize source dimensions and encoding, avoid transferring assets larger than the preview requires, and preload only genuinely critical media. Shared caching improves repeated access, not the inherent cost of the initial fill.

Local access works but the public URL does not

Confirm that the Localtonet client is connected, the tunnel has been started, and the configured local IP and port match the listening service. If the application binds only to an interface the client cannot reach, adjust the application binding according to that project's documented security model. Also check whether the development server validates the request host or origin. Do not disable host protection broadly without understanding the security effect.

The public page works, but hot reload or live updates fail

Development live-reload channels can use WebSockets or other persistent connections and are not cacheable media requests. Ensure that any separately configured reverse proxy passes those connections without trying to cache them. The exact configuration depends on the application framework and proxy. Localtonet supports HTTP/s tunneling, but this guide does not invent framework-specific origin or host settings where no verified project configuration has been supplied.

Frequently asked questions