How jub0bs/cors works
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.Handlers, 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 Middleware · config.go Config validation & compilation · origins.go Origin policy engine · req.go Request header parsing
Components 19
Public API
Consumer-facing library boundary.
- Embedding application · Owns the server, router, and downstream handlers.
- Package documentation
doc.go - Config · Declarative CORS security policy and construction boundary.
config.go - Middleware · Wraps handlers and safely publishes recompiled policy.
middleware.go
Policy Compilation
Validates and compiles declarative CORS policy.
- Configuration errors
cfgerrors/cfgerrors.go - Config validation & compilation · Converts validated settings into request-time representations.
config.go
Request Processing
Classifies requests and enforces compiled policy.
- Request header parsing · Classifies Origin and preflight request headers.
internal/headers/req.go - Requested-header parser
internal/headers/acrh.go - Response header policy · Emits Access-Control-Allow and related protocol headers.
internal/headers/res.go - Wrapped handler flow · Permitted actual and non-CORS requests reach the application handler.
middleware.go
Internal Policy Engines
Replaceable matching, header, and collection internals.
- Method policy
internal/methods/methods.go - Origin policy engine · Parses allowed-origin patterns and authorizes request origins.
internal/origins/origins.go - Origin patterns
internal/origins/pattern.go - Origin radix index · Fast lookup for compiled origin mappings.
internal/origins/radix.go - Origin mapping
internal/origins/mapping.go - Sorted set · Supports deduplicated, ordered policy collections.
internal/sortedset/sortedset.go - Header protocol support
internal/headers/common.go
Build & CI
- Go module · Go 1.26+ library using the standard HTTP stack.
go.mod - GitHub Actions CI
.github/workflows/cors.yml
Connections 22
- 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