initial commit

.github/workflows/cors.yml

@@ -0,0 +1,64 @@
+name: build
+
+on: [push]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version: [1.22]
+    steps:
+      - name: Checkout Source
+        uses: actions/checkout@v4
+      - name: Setup Go ${{ matrix.go-version }}
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ matrix.go-version }}
+          cache: true
+      - name: Display Go version
+        run: go version
+      - name: Test
+        run: go test -v -coverprofile=cover.out ./...
+      - name: Upload coverage reports to Codecov
+        uses: codecov/[email protected]
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: jub0bs/cors
+  benchmark:
+    needs: test
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        go-version: [1.22]
+    name: Benchmark comparison ${{ matrix.os }} @ Go ${{ matrix.go-version }}
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout Code (previous)
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.base_ref }}
+          path: previous
+      - name: Checkout Code (new)
+        uses: actions/checkout@v4
+        with:
+          path: new
+      - name: Set up Go ${{ matrix.go-version }}
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ matrix.go-version }}
+      - name: Install benchstat
+        run: go install golang.org/x/perf/cmd/benchstat@latest
+      - name: Run Benchmark (previous)
+        run: |
+          cd previous
+          go test -run=^$ -bench=. -count=10 . -benchtime 10000x > benchmark.txt
+      - name: Run Benchmark (new)
+        run: |
+          cd new
+          go test -run=^$ -bench=. -count=10 . -benchtime 10000x > benchmark.txt
+      - name: Run benchstat
+        # Mostly to compare allocations;
+        # measurements of execution speed in GitHub Actions are unreliable.
+        run: |
+          benchstat previous/benchmark.txt new/benchmark.txt

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] (2024-03-23)
+
+[0.1.0]: https://github.com/jub0bs/cors/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing to jub0bs/cors
+
+jub0bs/cors is an open-source project
+but currently does not accept external contributions.
+
+However, if you want to report a problem (a bug, a missing feature,
+a misfeature, an idea for performance improvement, etc.),
+feel free to [open an issue](https://github.com/jub0bs/cors/issues/new).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 jub0bs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,148 @@
+# jub0bs/cors
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/jub0bs/cors.svg)](https://pkg.go.dev/github.com/jub0bs/cors)
+[![license](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat)](https://github.com/jub0bs/cors/raw/main/LICENSE)
+[![build](https://github.com/jub0bs/cors/actions/workflows/cors.yml/badge.svg)](https://github.com/jub0bs/cors/actions/workflows/cors.yml)
+[![codecov](https://codecov.io/gh/jub0bs/cors/branch/main/graph/badge.svg?token=N208BHWQTM)](https://app.codecov.io/gh/jub0bs/cors/tree/main)
+[![goreport](https://goreportcard.com/badge/jub0bs/cors)](https://goreportcard.com/report/jub0bs/cors)
+
+A principled [CORS][mdn-cors] middleware library for [Go][golang],
+designed to be both easier to use and harder to misuse
+than existing alternatives.
+
+## About CORS
+
+The [Same-Origin Policy (SOP)][mdn-sop] is a security mechanism that
+Web browsers implement to protect their users.
+In particular, the SOP places some restrictions on cross-origin network access,
+in terms of both sending and reading.
+[Cross-Origin Resource Sharing (CORS)][mdn-cors] is a protocol that
+lets servers instruct browsers to relax those restrictions for select clients.
+
+This package allows you to configure and build [net/http][net-http] middleware
+that implement CORS.
+
+## Installation
+
+```shell
+go get github.com/jub0bs/cors
+```
+
+jub0bs/cors requires Go 1.22 or above.
+
+## Example
+
+The following program demonstrates how to create a CORS middleware that
+
+- allows anonymous requests from Web origin `https://example.com`,
+- with any HTTP method among `GET`, `POST`, `PUT`, or `DELETE`, and
+- (optionally) with request header `Authorization`,
+
+and how to apply the middleware in question to all the resources accessible
+under some `/api/` path:
+
+```go
+package main
+
+import (
+  "fmt"
+  "io"
+  "log"
+  "net/http"
+
+  "github.com/jub0bs/cors"
+)
+
+func main() {
+  mux := http.NewServeMux()
+  mux.HandleFunc("GET /hello", handleHello) // note: not configured for CORS
+
+  // create CORS middleware
+  corsMw, err := cors.NewMiddleware(cors.Config{
+    Origins: []string{"https://example.com"},
+    Methods: []string{
+      http.MethodGet,
+      http.MethodPost,
+      http.MethodPut,
+      http.MethodDelete,
+    },
+    RequestHeaders: []string{"Authorization"},
+  })
+  if err != nil {
+    log.Fatal(err)
+  }
+  corsMw.SetDebug(true) // turn debug mode on (optional)
+
+  api := http.NewServeMux()
+  mux.Handle("/api/", corsMw.Wrap(api)) // note: method-less pattern here
+  api.HandleFunc("GET /api/users", handleUsersGet)
+  api.HandleFunc("POST /api/users", handleUsersPost)
+  api.HandleFunc("PUT /api/users", handleUsersPut)
+  api.HandleFunc("DELETE /api/users", handleUsersDelete)
+
+  log.Fatal(http.ListenAndServe(":8080", mux))
+}
+
+func handleHello(w http.ResponseWriter, _ *http.Request) {
+  io.WriteString(w, "Hello, World!")
+}
+
+func handleUsersGet(w http.ResponseWriter, _ *http.Request) {
+  // omitted
+}
+
+func handleUsersPost(w http.ResponseWriter, _ *http.Request) {
+  // omitted
+}
+
+func handleUsersPut(w http.ResponseWriter, _ *http.Request) {
+  // omitted
+}
+
+func handleUsersDelete(w http.ResponseWriter, _ *http.Request) {
+  // omitted
+}
+```
+
+Try it out yourself by saving this program to a file named `server.go`.
+You may need to adjust the port number if port 8080 happens to be unavailable
+on your machine. Then build and run your server:
+
+```shell
+go build server.go
+./server
+```
+
+If no error occurred, the server is now running on `localhost:8080` and
+the various resources accessible under the `/api/` path are now configured
+for CORS as desired.
+
+## Documentation
+
+The documentation is available on [pkg.go.dev][pkgsite].
+
+## Code coverage
+
+![coverage](https://codecov.io/gh/jub0bs/cors/branch/main/graphs/sunburst.svg?token=N208BHWQTM)
+
+## License
+
+All source code is covered by the [MIT License][license].
+
+## Additional resources
+
+- [_Fearless CORS: a design philosophy for CORS middleware libraries
+(and a Go implementation)_][fearless-cors] (blog post)
+- [_Useful Functional-Options Tricks for Better Libraries_
+(GopherCon Europe 2023)][funcopts] (video)
+- [github.com/jub0bs/fcors][fcors] (this library's predecessor)
+
+[fcors]: https://github.com/jub0bs/fcors
+[fearless-cors]: https://jub0bs.com/posts/2023-02-08-fearless-cors/
+[funcopts]: https://www.youtube.com/watch?v=5uM6z7RnReE
+[golang]: https://go.dev/
+[license]: https://github.com/jub0bs/cors/blob/main/LICENSE
+[mdn-cors]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
+[mdn-sop]: https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy
+[net-http]: https://pkg.go.dev/net/http
+[pkgsite]: https://pkg.go.dev/github.com/jub0bs/cors

SECURITY.md

@@ -0,0 +1,6 @@
+## Reporting security issue
+
+Please do **not** open an issue on GitHub.
+Instead, contact jub0bs privately on [Mastodon].
+
+[Mastodon]: https://infosec.exchange/@jub0bs