# jub0bs/cors architecture

> Architecture diagram of the GitHub repository jub0bs/cors, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jub0bs/cors
- Repository: https://github.com/jub0bs/cors

## Overview

#### Purpose and runtime

This is a Go 1.26+ library, not an application: it produces `net/http` middleware implementing Fetch-standard CORS behavior. Consumers construct a middleware instance, wrap selected `http.Handler`s, and run those handlers in their own server/router. There is no repository-hosted service, database, or deployment runtime.

Core public entry points:
- `Config` and configuration construction/validation: `config.go`
- `NewMiddleware`, handler wrapping, debug, and runtime reconfiguration: `middleware.go`
- Programmatic configuration error types: `cfgerrors/cfgerrors.go`
- Package-level API documentation: `doc.go`

#### Configuration compilation boundary

`Config` is the declarative, user-controlled security boundary. Middleware construction validates configuration early and converts it into efficient immutable/internal representations before serving traffic. Invalid or unsafe settings are surfaced as ordinary Go errors, including typed errors from `cfgerrors`.

Key paths:
- `config.go`
- `cfgerrors/cfgerrors.go`
- `internal/methods/methods.go`

Configured methods are normalized/represented by the methods subsystem; request headers and response policy are similarly compiled through internal header support. This separation keeps expensive validation and canonicalization off the per-request path.

#### Origin policy engine

Origin matching is the primary CORS authorization decision. The origins subsystem parses the restricted origin-pattern language, supports exact and pattern-based matching, and organizes allowed origins for fast lookup.

Key paths:
- `internal/origins/origins.go`
- `internal/origins/pattern.go`
- `internal/origins/radix.go`

`mapping.go` and the radix structure indicate a compiled matcher rather than linear request-time scans. Go-version-specific implementations (`internal/origins/go127.go`, `internal/origins/notgo127.go`) isolate compatibility/performance behavior behind this internal boundary.

#### HTTP request classification and CORS execution

The `Middleware` produced in `middleware.go` is the request-time control point. Wrapped handlers receive ordinary/non-CORS requests and permitted actual CORS requests; CORS preflight requests are handled directly by the middleware, returning the fixed successful preflight status described by the README rather than reaching the application handler.

Key paths:
- `middleware.go`
- `internal/headers/req.go`
- `internal/headers/acrh.go`

Incoming `Origin`, requested method, and `Access-Control-Request-Headers` are parsed/classified first. The middleware then checks the compiled origin, method, and header policy. Failed CORS authorization is prevented from receiving CORS permission headers; preflight failure is terminated before downstream application execution.

#### Response header policy

Internal header modules centralize recognition and output of CORS protocol headers, separating HTTP wire concerns from middleware orchestration.

Key paths:
- `internal/headers/common.go`
- `internal/headers/res.go`
- `internal/headers/req.go`

On authorized requests/preflights, this layer emits the appropriate `Access-Control-Allow-*` and related response headers. Header-name handling and preflight requested-header parsing are explicit concerns, helping preserve the stated casing/order/performance expectations.

#### Dynamic state and concurrency

The middleware supports on-the-fly reconfiguration and debug mode while serving requests. The architectural implication is a mutable public `Middleware` façade over safely replaceable compiled configuration/state, so reconfiguration must repeat validation/compilation before publishing a new policy to concurrent request handling.

Key paths:
- `middleware.go`
- `config.go`
- `cfgerrors/cfgerrors.go`

Debug is intentionally diagnostic rather than request logging; the library remains embedded in the caller’s `net/http` stack and does not own logging or server lifecycle.

#### Supporting data structures and quality boundary

A small sorted-set primitive likely supports canonical, deduplicated policy/header collections used by compiled configuration. Internal packages are deliberately inaccessible to library consumers, preserving freedom to optimize matching and header processing without public API changes.

Key paths:
- `internal/sortedset/sortedset.go`
- `internal/origins/mapping.go`
- `go.mod`

External dependencies are primarily the Go standard library, especially `net/http`; browser Fetch/CORS semantics are the external protocol contract. GitHub Actions executes the repository’s CI workflow at `.github/workflows/cors.yml`.

Main entry points: [`middleware.go`](https://github.com/jub0bs/cors/blob/main/middleware.go) (Middleware), [`config.go`](https://github.com/jub0bs/cors/blob/main/config.go) (Config validation & compilation), [`internal/origins/origins.go`](https://github.com/jub0bs/cors/blob/main/internal/origins/origins.go) (Origin policy engine), [`internal/headers/req.go`](https://github.com/jub0bs/cors/blob/main/internal/headers/req.go) (Request header parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_consumer(("Embedding application<br/>net/http consumer"))
  node_docs["Package documentation<br/>Go package docs<br/>[doc.go]"]
  node_config["Config<br/>[config.go]"]
  node_middleware["Middleware<br/>[middleware.go]"]
end

subgraph group_compile["Policy Compilation"]
  node_cfgerrors["Configuration errors<br/>typed errors<br/>[cfgerrors.go]"]
  node_compiler{{"Config validation &amp; compilation<br/>policy compiler<br/>[config.go]"}}
end

subgraph group_runtime["Request Processing"]
  node_requestheaders["Request header parsing<br/>CORS request parser<br/>[req.go]"]
  node_requestedheaders["Requested-header parser<br/>ACRH parser<br/>[acrh.go]"]
  node_responseheaders["Response header policy<br/>CORS response writer<br/>[res.go]"]
  node_wrappedhandler["Wrapped handler flow<br/>net/http execution<br/>[middleware.go]"]
end

subgraph group_internal["Internal Policy Engines"]
  node_methods["Method policy<br/>method compiler<br/>[methods.go]"]
  node_origins{{"Origin policy engine<br/>compiled matcher<br/>[origins.go]"}}
  node_patterns["Origin patterns<br/>pattern parser<br/>[pattern.go]"]
  node_radix["Origin radix index<br/>matcher index<br/>[radix.go]"]
  node_mapping["Origin mapping<br/>compiled mapping<br/>[mapping.go]"]
  node_sortedset["Sorted set<br/>canonical collection<br/>[sortedset.go]"]
  node_headercommon["Header protocol support<br/>header definitions<br/>[common.go]"]
end

subgraph group_quality["Build &amp; CI"]
  node_gomod["Go module<br/>module definition<br/>[go.mod]"]
  node_ci["GitHub Actions CI<br/>CI workflow<br/>[cors.yml]"]
end

node_consumer -->|"declares policy"| node_config
node_consumer -->|"constructs and wraps handlers"| node_middleware
node_docs -.->|"documents API"| node_middleware
node_config -->|"validates and compiles"| node_compiler
node_compiler -->|"returns invalid-policy errors"| node_cfgerrors
node_compiler -->|"compiles methods"| node_methods
node_compiler -->|"compiles origins"| node_origins
node_compiler -->|"canonicalizes collections"| node_sortedset
node_origins -->|"parses patterns"| node_patterns
node_origins -->|"builds mappings"| node_mapping
node_mapping -->|"indexes lookup"| node_radix
node_middleware -->|"initial and dynamic reconfiguration"| node_compiler
node_middleware -->|"classifies requests"| node_requestheaders
node_requestheaders -->|"parses preflight headers"| node_requestedheaders
node_middleware -->|"checks origin"| node_origins
node_middleware -->|"checks requested method"| node_methods
node_middleware -->|"writes authorized CORS headers"| node_responseheaders
node_requestheaders -->|"uses header recognition"| node_headercommon
node_responseheaders -->|"uses protocol headers"| node_headercommon
node_middleware -->|"forwards allowed actual requests"| node_wrappedhandler
node_wrappedhandler -->|"invokes downstream handler"| node_consumer
node_ci -->|"builds and tests module"| node_gomod

click node_docs "https://github.com/jub0bs/cors/blob/main/doc.go"
click node_config "https://github.com/jub0bs/cors/blob/main/config.go"
click node_middleware "https://github.com/jub0bs/cors/blob/main/middleware.go"
click node_cfgerrors "https://github.com/jub0bs/cors/blob/main/cfgerrors/cfgerrors.go"
click node_compiler "https://github.com/jub0bs/cors/blob/main/config.go"
click node_methods "https://github.com/jub0bs/cors/blob/main/internal/methods/methods.go"
click node_origins "https://github.com/jub0bs/cors/blob/main/internal/origins/origins.go"
click node_patterns "https://github.com/jub0bs/cors/blob/main/internal/origins/pattern.go"
click node_radix "https://github.com/jub0bs/cors/blob/main/internal/origins/radix.go"
click node_mapping "https://github.com/jub0bs/cors/blob/main/internal/origins/mapping.go"
click node_sortedset "https://github.com/jub0bs/cors/blob/main/internal/sortedset/sortedset.go"
click node_requestheaders "https://github.com/jub0bs/cors/blob/main/internal/headers/req.go"
click node_requestedheaders "https://github.com/jub0bs/cors/blob/main/internal/headers/acrh.go"
click node_responseheaders "https://github.com/jub0bs/cors/blob/main/internal/headers/res.go"
click node_headercommon "https://github.com/jub0bs/cors/blob/main/internal/headers/common.go"
click node_wrappedhandler "https://github.com/jub0bs/cors/blob/main/middleware.go"
click node_gomod "https://github.com/jub0bs/cors/blob/main/go.mod"
click node_ci "https://github.com/jub0bs/cors/blob/main/.github/workflows/cors.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_consumer,node_docs,node_config,node_middleware toneBlue
class node_cfgerrors,node_compiler toneAmber
class node_requestheaders,node_requestedheaders,node_responseheaders,node_wrappedhandler toneMint
class node_methods,node_origins,node_patterns,node_radix,node_mapping,node_sortedset,node_headercommon toneRose
class node_gomod,node_ci toneIndigo
```

## Components

### Public API

Consumer-facing library boundary.

- **Embedding application**: net/http consumer · Owns the server, router, and downstream handlers.
- [Package documentation](https://github.com/jub0bs/cors/blob/main/doc.go): Go package docs · `doc.go`
- [Config](https://github.com/jub0bs/cors/blob/main/config.go): public configuration · Declarative CORS security policy and construction boundary. · `config.go`
- [Middleware](https://github.com/jub0bs/cors/blob/main/middleware.go): public middleware · Wraps handlers and safely publishes recompiled policy. · `middleware.go`

### Policy Compilation

Validates and compiles declarative CORS policy.

- [Configuration errors](https://github.com/jub0bs/cors/blob/main/cfgerrors/cfgerrors.go): typed errors · `cfgerrors/cfgerrors.go`
- [Config validation & compilation](https://github.com/jub0bs/cors/blob/main/config.go): policy compiler · Converts validated settings into request-time representations. · `config.go`

### Request Processing

Classifies requests and enforces compiled policy.

- [Request header parsing](https://github.com/jub0bs/cors/blob/main/internal/headers/req.go): CORS request parser · Classifies Origin and preflight request headers. · `internal/headers/req.go`
- [Requested-header parser](https://github.com/jub0bs/cors/blob/main/internal/headers/acrh.go): ACRH parser · `internal/headers/acrh.go`
- [Response header policy](https://github.com/jub0bs/cors/blob/main/internal/headers/res.go): CORS response writer · Emits Access-Control-Allow and related protocol headers. · `internal/headers/res.go`
- [Wrapped handler flow](https://github.com/jub0bs/cors/blob/main/middleware.go): net/http execution · Permitted actual and non-CORS requests reach the application handler. · `middleware.go`

### Internal Policy Engines

Replaceable matching, header, and collection internals.

- [Method policy](https://github.com/jub0bs/cors/blob/main/internal/methods/methods.go): method compiler · `internal/methods/methods.go`
- [Origin policy engine](https://github.com/jub0bs/cors/blob/main/internal/origins/origins.go): compiled matcher · Parses allowed-origin patterns and authorizes request origins. · `internal/origins/origins.go`
- [Origin patterns](https://github.com/jub0bs/cors/blob/main/internal/origins/pattern.go): pattern parser · `internal/origins/pattern.go`
- [Origin radix index](https://github.com/jub0bs/cors/blob/main/internal/origins/radix.go): matcher index · Fast lookup for compiled origin mappings. · `internal/origins/radix.go`
- [Origin mapping](https://github.com/jub0bs/cors/blob/main/internal/origins/mapping.go): compiled mapping · `internal/origins/mapping.go`
- [Sorted set](https://github.com/jub0bs/cors/blob/main/internal/sortedset/sortedset.go): canonical collection · Supports deduplicated, ordered policy collections. · `internal/sortedset/sortedset.go`
- [Header protocol support](https://github.com/jub0bs/cors/blob/main/internal/headers/common.go): header definitions · `internal/headers/common.go`

### Build & CI

- [Go module](https://github.com/jub0bs/cors/blob/main/go.mod): module definition · Go 1.26+ library using the standard HTTP stack. · `go.mod`
- [GitHub Actions CI](https://github.com/jub0bs/cors/blob/main/.github/workflows/cors.yml): CI workflow · `.github/workflows/cors.yml`

## Connections

- Embedding application → Config: declares policy
- Embedding application → Middleware: constructs and wraps handlers
- Package documentation → Middleware: documents API
- Config → Config validation & compilation: validates and compiles
- Config validation & compilation → Configuration errors: returns invalid-policy errors
- Config validation & compilation → Method policy: compiles methods
- Config validation & compilation → Origin policy engine: compiles origins
- Config validation & compilation → Sorted set: canonicalizes collections
- Origin policy engine → Origin patterns: parses patterns
- Origin policy engine → Origin mapping: builds mappings
- Origin mapping → Origin radix index: indexes lookup
- Middleware → Config validation & compilation: initial and dynamic reconfiguration
- Middleware → Request header parsing: classifies requests
- Request header parsing → Requested-header parser: parses preflight headers
- Middleware → Origin policy engine: checks origin
- Middleware → Method policy: checks requested method
- Middleware → Response header policy: writes authorized CORS headers
- Request header parsing → Header protocol support: uses header recognition
- Response header policy → Header protocol support: uses protocol headers
- Middleware → Wrapped handler flow: forwards allowed actual requests
- Wrapped handler flow → Embedding application: invokes downstream handler
- GitHub Actions CI → Go module: builds and tests module
