Modernizing Plugin WebViews with a Local Assets Server

WebViews are simple until they need to behave like the web.

GoodBarber plugins are web experiences embedded in generated native applications. Their HTML, JavaScript, CSS, fonts, images, and media can live on the device, while the page still needs browser storage, JavaScript modules, remote APIs, cookies, streaming, navigation, and the native GoodBarber bridge.

I modernized that environment by moving packaged plugin content onto a real loopback HTTP origin and building the routing, proxying, security, and recovery infrastructure around it. The project sat at the intersection of WebKit, Network.framework, HTTP semantics, JavaScript interception, native lifecycle management, and backward compatibility.

Why a Real Origin Was Necessary

Custom native schemes can load files, but they do not behave exactly like http or https. Modern Web APIs make decisions using the document origin and security context. Modules, fetch, XHR, media elements, cookies, storage, relative navigation, and embedded frameworks can all expose differences.

The goal was not to turn plugins into remote websites. Their assets should remain local. The goal was to present those local assets to WKWebView through the standard semantics it already understands:

• an http://127.0.0.1:PORT origin
• normal request and response headers
• MIME types and status codes
• same-origin relative asset loading
• GET, HEAD, keep-alive, and byte ranges
• a controlled path for cross-origin network requests

That required more than adding a listener. It required a small, deliberate web runtime inside the app.

Registering a Scoped Plugin Runtime

An Objective-C-compatible local-server facade is used by sections, embedded content blocks, and plugins. The first registration starts the server lazily, waits for the underlying NWListener to become ready, registers the caller’s folder as a scoped resource, and returns the base URL that its WebView should use.

The server distinguishes sections, widgets, and plugins in the URL path. Registrations are reference counted, so two WebViews can safely share the same scope and the folder mapping is removed only after the final unregister. This matters during rapid navigation, repeated view creation, and recovery paths that rebuild a WebView.

The URL has a deliberate structure:

http://127.0.0.1:PORT/<session-token>/<scope-kind>/<scope-id>/...

The port is derived deterministically from the application bundle identifier using a stable FNV-1a hash. A stable port preserves the WebKit origin across normal launches, which helps cookies and site data remain associated with the same origin. If that port is unavailable, the server falls back to an operating-system-selected port instead of failing the plugin.

The session token is 128 bits of cryptographically random data generated on cold start. It sits in the path rather than the host, so it gates requests without changing the WebKit origin. A sibling process can scan loopback ports, but it cannot retrieve assets without knowing the token.

From Plugin Files to a WebView Document

The plugin section registers its folder before constructing the embedded WebView. The returned scope URL becomes the WebView’s base URL and identifies the exact local folder the server is allowed to expose.

Plugin HTML is generated with the existing CSS, JavaScript, and native bridge integration, then written to disk inside that registered folder. The controller uses loadRequest on the loopback document URL rather than loadHTMLString. That distinction is important: injecting a string with a base URL is not equivalent to navigating to an HTTP document. Loading the on-disk document through the server gives the page the real loopback origin and security context the architecture is designed around.

Moving from historical URL assumptions to relative HTTP navigation required an asset URL rewriter. It processes text-based plugin files such as HTML, CSS, JavaScript, modules, and SVG. It knows the assets present in the plugin folder and normalizes supported references to bare relative paths, including query-string variants. It intentionally avoids rewriting arbitrary quoted JavaScript strings, which could be data rather than URLs.

The result is a document tree that resolves naturally inside its scoped loopback path. Links to other plugin pages can be translated back into the engine’s internal navigation model when needed, while images, scripts, styles, and media remain ordinary relative HTTP resources.

A Real HTTP Connection Layer

The local assets server uses an IPv4 NWListener restricted to the loopback interface. Each accepted NWConnection is owned by a per-connection HTTP handler, which incrementally buffers bytes, parses HTTP request heads and bodies, enforces request-size limits, and supports multiple keep-alive requests without allowing a streamed proxy response to interleave with another request.

Every route validates the session token before resolving a scope. Asset requests then map the scope kind and identifier to the registered folder. The candidate path is standardized and symlinks are resolved before checking that it remains under the registered root. That closes both ../ traversal and symlink escape routes.

The file-serving path supports GET and HEAD, derives MIME types through UniformTypeIdentifiers, and returns 404, 403, or 405 for the corresponding failure classes. It also implements single byte-range requests and 206 Partial Content, including Content-Range and Accept-Ranges headers. That makes local audio and video seeking behave like normal HTTP media instead of forcing WebKit to download a complete file before playback.

Cross-Origin Requests Without Disabling Web Security

A loopback page that calls a remote API is cross-origin, so browser CORS rules apply. The solution was not to globally weaken WebKit. I built a scoped same-origin proxy composed of two halves.

At document start, the embedded WebView injects a request-interception script. The script activates only for pages running on http://127.0.0.1. It leaves same-origin resources and non-HTTP schemes untouched, but wraps cross-origin fetch and XHR URLs into a path under the plugin’s own loopback scope.

The proxy path contains the credential mode, upstream scheme, authority, path, and query. Keeping the upstream hierarchy in the path has an important benefit: relative child URLs in resources such as HLS manifests continue resolving through the proxy instead of falling back to the loopback asset root.

The native connection validates that the proxy request plausibly originated from the loopback page, reconstructs only http or https targets, and rejects literal loopback, private, and link-local addresses. Redirects are checked again, and cookies or authorization headers are removed when a redirect crosses origins. This provides an SSRF safety floor instead of turning the proxy into an unrestricted tunnel.

Hop-by-hop, framing, origin, referer, encoding, and direct cookie headers are stripped before the request is forwarded through URLSession. When credentials are allowed, a cookie bridge reads only cookies applicable to the upstream host, path, and security level from the WebKit cookie store. Upstream Set-Cookie values are stored against the remote origin and removed from the loopback response, preventing them from becoming shared loopback cookies visible to unrelated plugin pages.

Streaming and Backpressure

Proxying remote media or large responses cannot rely on buffering the entire body in memory. The connection sends the upstream response head first, then relays body data with HTTP/1.1 chunked transfer encoding.

The write queue preserves byte order and allows only one NWConnection send at a time. If pending bytes cross a threshold because the WebView is reading more slowly than the upstream server is producing data, the URLSessionTask is suspended. It resumes when the queue drains below a lower threshold. This backpressure prevents an unbounded memory build-up during long downloads or media streams.

Failure semantics also matter. If the upstream request fails before headers arrive, the proxy can return a clean 502 Bad Gateway. If failure occurs after streaming has begun, it closes the connection after draining queued bytes rather than sending a successful chunk terminator for a truncated response.

Surviving iOS Suspension

A loopback listener can be healthy when the app enters the background and dead when it returns. Recovery therefore belongs to the infrastructure rather than to individual plugin pages.

The local-server manager tracks explicit server states: stopped, starting, ready, waiting, and failed. On application or scene activation, it revives only a failed listener by stopping the dead instance and creating a new one. Restart attempts are rate limited to avoid a hot loop if the operating system repeatedly kills the listener.

After a successful restart, the manager publishes a notification on the main queue. Loopback-backed plugin WebViews reload their current page, while external WebViews ignore it. Plugin controllers also track whether their WebView had loaded successfully and use a bounded retry budget for server registration failures, WebKit process termination, and network-layer navigation errors.

This is important because several failures can look identical from inside WebKit: the listener may have died, the Web content process may have been terminated, or the page may have encountered an ordinary navigation error. The recovery path retries only network-layer failures, ignores cancellations, waits briefly before reloading, and calls ensureRunning() before issuing the next request.

Preserving the Native Plugin Contract

The local origin changed asset delivery, not the product contract. The embedded WebView still injects the platform JavaScript bridge when needed, forwards native lifecycle events, publishes login and logout changes, handles navigation policy, and exposes plugin-management capabilities.

That compatibility boundary was essential. Existing plugins had years of assumptions around bridge callbacks and app lifecycle events. The new transport needed to improve browser compatibility without asking plugin authors to rewrite their integration with the native engine.

What the Architecture Achieved

The result is a constrained local web runtime rather than a file-loading workaround:

• scoped and token-protected local assets
• a stable HTTP origin with deterministic-port fallback
• correct MIME, HEAD, keep-alive, and byte-range behavior
• relative asset migration for existing plugin packages
• a same-origin proxy with credential, redirect, and SSRF controls
• streamed responses with backpressure
• lifecycle recovery after listener or WebKit process failure
• continued support for the native JavaScript bridge

When this infrastructure works, plugin authors do not have to understand it. They get behavior closer to a normal web environment, while the iOS engine retains control over local files, outbound networking, cookies, lifecycle recovery, and native capabilities.