Configuring CORS

Cross-Origin Resource Sharing (CORS) controls which origins can access your application from a web browser.

Mach lets you configure a CORS policy when building the application.

Enabling CORS

Use AppBuilder::addCors() to configure CORS:

int main() {
    mach::AppBuilder builder;

    builder.addCors([](mach::CorsBuilder& cors) {
        cors.allowOrigin("https://example.com");
    });
}

This allows browser requests to the application from https://example.com.

Requests from other origins are not allowed by this policy.

Allowing Methods and Headers

A CORS policy can restrict which HTTP methods and request headers are allowed.

For example, an API used by a frontend application might allow GET and POST requests with a Content-Type header:

builder.addCors([](mach::CorsBuilder& cors) {
    cors.allowOrigin("https://app.example.com")
        .allowMethods({
            mach::http::Method::Get,
            mach::http::Method::Post
        })
        .allowHeader("Content-Type");
});

Only allow the methods, headers, and origins your application actually needs.

Allowing Multiple Origins

Use allowOrigins() when several known origins need access to the application:

builder.addCors([](mach::CorsBuilder& cors) {
    cors.allowOrigins({
        "https://app.example.com",
        "https://admin.example.com",
        "http://localhost:3000"
    });
});

This is useful when the same API is accessed by multiple frontends or by both production and local development environments.

Allowing Credentials

Cross-origin requests that include credentials, such as cookies, require credentials to be enabled by the CORS policy.

builder.addCors([](mach::CorsBuilder& cors) {
    cors.allowOrigin("https://app.example.com")
        .allowCredentials();
});

The client must also configure the request to include credentials.

When credentials are enabled, prefer explicitly allowing trusted origins rather than using a broadly permissive CORS policy.

Preflight Requests

For some cross-origin requests, browsers first send an OPTIONS request called a preflight request.

The preflight checks whether the server permits the requested origin, HTTP method, and headers before the browser sends the actual request.

A CORS policy might therefore look like:

builder.addCors([](mach::CorsBuilder& cors) {
    cors.allowOrigin("https://app.example.com")
        .allowMethods({
            mach::http::Method::Get,
            mach::http::Method::Post,
            mach::http::Method::Delete
        })
        .allowHeaders({
            "Content-Type",
            "Authorization"
        });
});

Preflight responses can also be cached by the browser:

builder.addCors([](mach::CorsBuilder& cors) {
    cors.allowOrigin("https://app.example.com")
        .allowAnyMethod()
        .allowAnyHeader()
        .maxAge(std::chrono::hours(1));
});

This tells the browser that it may cache the preflight result for up to one hour.

Allowing Any Origin

For public APIs or development environments, you can create a permissive policy:

builder.addCors([](mach::CorsBuilder& cors) {
    cors.allowAnyOrigin()
        .allowAnyMethod()
        .allowAnyHeader();
});

This allows requests from any origin using any method and request headers.

For applications that are not intended to be publicly accessible from arbitrary origins, prefer explicitly listing the origins and capabilities that should be allowed.

---

Next Steps

For the complete CORS configuration API, see CorsBuilder.