WeAmp.PageSpeed.NativeAssets.Windows 2.1.0

WeAmp.PageSpeed for ASP.NET Core

Drop-in ASP.NET Core middleware that improves Core Web Vitals without touching your app code. It adds critical CSS inlining, LCP preload injection, lazy loading, and on-demand WebP/AVIF image transcoding to every HTML response. The C++23 PageSpeed engine runs in-process via P/Invoke and serves cache hits zero-copy.

Single-package install. Hot-reloadable config. Optimization runs out of the box.

Quick Start

1. Install the package

dotnet add package WeAmp.PageSpeed.AspNetCore

The matching native binaries for your runtime (linux-x64, linux-arm64, osx-arm64, or win-x64) come in transitively: no separate NativeAssets package reference required.

2. Register the middleware in Program.cs

using WeAmp.PageSpeed.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddPageSpeed();

var app = builder.Build();

app.UsePageSpeed();    // before anything that writes the response body
app.UseStaticFiles();

app.Run();

No extra wiring required: with no Worker section, the worker process starts automatically and coordinates over an auto-resolved per-process socket. Add a Worker section only to change that — see Configuration. Optimization is on by default.

3. How do I know it's working?

Three checks, from quickest to most thorough. These examples assume your app listens on :5050 (set ASPNETCORE_URLS=http://localhost:5050 or adjust the URLs to your port) and serves at least one HTML page and one image.

Hit a content route and look for the X-PageSpeed header:

curl -i http://localhost:5050/

HTTP/1.1 200 OK
X-PageSpeed: HIT

HIT means the response was served from the optimized cache; MISS means the worker is building the variant and you'll see HIT on the next request. (The /console/* routes are short-circuited before the middleware, so they intentionally do not carry X-PageSpeed — only content routes like / and your assets do.)

Open http://localhost:5050/console/. Once a few requests have run, the Dashboard and Metrics show non-zero counts. If everything reads zero, see How do I know it's working? in the docs.

Confirm image transcoding via content negotiation. We don't rewrite URLs in 2.0: the same /hero.jpg URL serves WebP to WebP-capable clients and AVIF to AVIF-capable ones, selected by the request Accept header:

curl -s -o /dev/null -D - http://localhost:5050/hero.jpg -H 'Accept: image/jpeg'
# Content-Length: 98230   Content-Type: image/jpeg   Vary: Accept, Save-Data, User-Agent

curl -s -o /dev/null -D - http://localhost:5050/hero.jpg -H 'Accept: image/webp'
# Content-Length: 2422    Content-Type: image/webp   Vary: Accept, Save-Data, User-Agent

curl -s -o /dev/null -D - http://localhost:5050/hero.jpg -H 'Accept: image/avif'
# Content-Length: 415     Content-Type: image/avif   Vary: Accept, Save-Data, User-Agent

Same URL, materially smaller bytes, and a Vary: Accept, Save-Data, User-Agent header so caches keep the variants apart. (Byte counts are from one sample image; yours will differ.)

What It Does

• HTML optimization: critical CSS inlining, lazy loading, LCP preload injection, third-party preconnect hints
• Image transcoding: on-demand conversion to WebP and AVIF, viewport-aware resizing, Save-Data support
• CSS/JS minification: whitespace removal, comment stripping
• Zero-copy caching: cache hits served from the memory-mapped Cyclone cache with no copy, up to 36 optimized variants per resource (format × viewport × density × Save-Data)

The middleware buffers HTML responses, passes them through the native libpagespeed library, and notifies the worker process to generate optimized asset variants asynchronously.

Platform Support

Native binaries (libpagespeed, factory_worker) are bundled with the matching WeAmp.PageSpeed.NativeAssets.* package, pulled in transitively by WeAmp.PageSpeed.AspNetCore. The worker process starts automatically on application boot. The Linux binaries statically link the C++ runtime (libc++/libc++abi/libunwind), so no additional shared libraries need to be present on the host beyond the system glibc.

On Linux and want a reverse proxy instead of in-process middleware? WeAmp.PageSpeed.Sidecar runs mod_pagespeed 1.15 as a bundled nginx + ngx_pagespeed reverse proxy in front of Kestrel (Linux-only). Use it when you want the classic nginx module in a sidecar; use this package for cross-platform in-process optimization with WebP/AVIF.

Each NativeAssets package also ships a BUILD_INFO.json file at runtimes/<rid>/native/BUILD_INFO.json with git_sha, git_sha_short, build_timestamp_utc, and rid. It is intended for support correlation and for verifying package provenance without running the worker.

Configuration

Add a PageSpeed section to appsettings.json. Only Cache is shown below; every key in the table is optional and falls back to its default.

{
  "PageSpeed": {
    "Cache": {
      "VolumePath": "/var/cache/pagespeed/volume.dat",
      "VolumeSizeBytes": 1073741824
    }
  }
}

Set Cache.VolumePath to a location that is writable in your environment. The default /var/cache/pagespeed/ assumes a Linux host; on Windows, macOS, or containers without that path, point it somewhere writable (for example ./cache/volume.dat or %TEMP%).

Top-level keys:

Cache section:

Worker section:

Console section:

Options support hot-reload via IOptionsMonitor<PageSpeedOptions>.

Worker IPC

The middleware ↔ worker channel uses Unix domain sockets on Linux and macOS, and Windows Named Pipes on win-x64. Selection is automatic; no configuration required. The console and its worker-API proxy are served on the app port; the worker's HTTP API is bound to 127.0.0.1 on an ephemeral port by default and is not exposed externally unless you set Worker.ApiPort explicitly.

Security

The /console/ admin console and its /v1/* worker-API proxy are served on the same origin as your app. The worker requires X-Requested-With: XMLHttpRequest on state-changing (POST/PATCH) requests, which blocks cross-origin form posts. It does not protect against same-origin scripts: a third-party script loaded into your app (via XSS or a supply-chain dependency) can drive the console API — for example purge the cache or change the worker configuration — because the in-process worker API is reachable through the proxy without a credential.

Treat /console/ as an admin surface:

• Set Console.RequireHttps = true in production.
• Don't expose /console/ to untrusted networks. Gate it at your reverse proxy, or use Console.MountPath to move the path off a guessable location.
• Avoid loading untrusted third-party scripts into apps with this middleware enabled.

License

Apache License 2.0, see the LICENSE file in the package.

Links

• modpagespeed.com/pricing/ — plans, pricing, and purchase
• modpagespeed.com/features/#aspnet-core — ASP.NET Core overview
• WeAmp.PageSpeed.Sidecar — mod_pagespeed 1.15 as a bundled-nginx sidecar (Linux)
• modpagespeed.com — product documentation and filter reference
• we-amp.com — We-Amp B.V.