warp-cors

warp-cors is a proxy server which enables CORS for the proxied request.

The path of the request is validated and then used as the url to proxy. Only http and https protocols are allowed and must be specified.

Preflight OPTIONS requests are answered locally by echoing Access-Control-Request-Method and Access-Control-Request-Headers into Access-Control-Allow-Methods and Access-Control-Allow-Headers. There is no method or header allowlist. Access-Control-Request-Method is required, while Access-Control-Request-Headers is optional. When no headers are requested, Access-Control-Allow-Headers is omitted. Preflight responses also vary by Access-Control-Request-Method and Access-Control-Request-Headers.

Successful proxy and preflight responses echo a valid serialized request Origin (such as https://example.org or the opaque origin null) in Access-Control-Allow-Origin and set Access-Control-Allow-Credentials: true. When no Origin is supplied, they use Access-Control-Allow-Origin: * and omit Access-Control-Allow-Credentials. Invalid origins receive neither header. Responses include Vary: Origin, preserving any upstream Vary fields; an existing Vary: * already covers all request headers.

Proxied responses list the forwarded upstream response header names in Access-Control-Expose-Headers, making those headers readable by browser JavaScript. Upstream Set-Cookie headers are removed, and request Cookie headers are not forwarded upstream.

Connection-specific headers are removed in both directions, including headers named by any Connection header. The HTTP client and server manage framing and connection headers for their respective connections.

Installation

Binaries

Archives of precompiled binaries are available for Linux, macOS, and Windows.

See VERIFYING.md for checksum and provenance verification before extracting or running downloaded archives.

The Windows binaries require Microsoft Visual C++ 2015 Redistributable to be installed.

Cargo

The minimum supported Rust version (MSRV) is 1.88.0.

$ cargo install warp-cors

Docker

Docker images are published in the bassetts/warp-cors repository.

See VERIFYING.md to verify an image's provenance and run the verified image by digest.

$ docker run -dp 3030:3030 bassetts/warp-cors

To build the image locally:

$ docker build -t warp-cors .

The Dockerfile pins the Rust compiler and both base images by digest, and builds with cargo build --locked --release to use the committed Cargo.lock. BuildKit caches downloaded crates and compiled dependencies between builds; these caches are excluded from the runtime image.

The runtime image contains Debian slim, the stripped executable, and a CA certificate bundle copied from the builder for HTTPS requests. No packages are downloaded during runtime image assembly. The existing weekly Docker Dependabot configuration proposes base image updates; merging them refreshes the image packages and certificate bundle. These pins make build inputs repeatable; image timestamps and build metadata can still differ between builds.

Usage

By default warp-cors will listen on port 3030 and use the package name (warp-cors) as the pseudonym in the Via header sent with the proxied request. These can be overwritten by using the --port <PORT> and --hostname <HOST> flags respectively.

If you are running warp-cors on a pubicly accessible hostname it is recommended to set the --hostname flag to match.

Example

$ warp-cors --port 3000 --hostname cors.example.org

Example requests

http://localhost:3030/ # 404 Not Found
http://localhost:3030/http://example.org # Proxied HTTP response with CORS headers
http://localhost:3030/https://example.org # Proxied HTTPS response with CORS headers
http://localhost:3030/example.org # 404 Not Found (no scheme provided)
http://localhost:3030/ftp://example.org # 404 Not Found (invalid scheme provided)

Logging

warp-cors uses pretty_env_logger, so you can control log levels by setting the RUST_LOG environment variable. This is useful for both developing and for running warp-cors.

# Output all info level logs, including those from libraries used by warp-cors
$ RUST_LOG=info warp-cors

# Output info level logs for only warp-cors
$ RUST_LOG=warp_cors=info warp-cors

# Filter logging by module, useful for development or debugging
$ RUST_LOG=warp_cors::filters::request=trace warp-cors

Releasing

See RELEASING.md for GitHub release, Docker, and crates.io publishing, including how to publish an existing tag.