Merge pull request #1 from bufbuild/ed/cors

Add CORS methods

README.md

@@ -1,9 +1,37 @@
 cors-go
 ===============
 
+Cross-origin resource sharing (CORS) support for Connect servers. Exports methods
+to configure CORS headers to allow Connect and gRPC-web protocols to operate in
+the browser.
+
+## Example
+
+As an example, we will use the [github.com/rs/cors](https://github.com/rs/cors) 
+package to demonstrate how to use the constants defined in this package.
+
+```go
+import (
+	cors "github.com/bufbuild/cors-go"
+	rscors "github.com/rs/cors"
+)
+
+// corsMiddleware wraps a handler with require cors config using rs/cors.
+func corsMiddleware(handler http.Handler) http.Handler {
+	// Create a new cors instance with default options.
+	c := rscors.New(rscors.Options{
+		AllowedMethods: cors.AllowedMethods(),
+		AllowedHeaders: cors.AllowedHeaders(),
+		ExposedHeaders: cors.ExposedHeaders(),
+	})
+	// Insert the middleware as a wrapper around your handler.
+	return c.Handler(handler /* connect handler */)
+}
+```
+
 ## Status: Alpha
 
-Always have a status section. See our other OSS repos for details.
+Cors is undergoing initial development and is not yet stable.
 
 ## Legal
 

cors.go

@@ -0,0 +1,76 @@
+// Copyright 2023 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package cors provides cross-origin resource sharing (CORS) constants for
+// Connect. These constants are used to configure the CORS headers for a
+// Connect server.
+package cors
+
+import "net/http"
+
+// AllowedMethods returns the allowed HTTP methods that scripts running in the
+// browser are permitted to use.
+//
+// To support cross-domain requests with the protocols supported by Connect,
+// these headers fields must be included in the preflight response header
+// Access-Control-Allow-Methods.
+func AllowedMethods() []string {
+	return []string{
+		http.MethodGet,  // Required for Connect GET requests
+		http.MethodPost, // Required for all protocols
+	}
+}
+
+// AllowedHeaders returns the allowed header fields that scripts running in the
+// browser are permitted to access.
+//
+// To support cross-domain requests with the protocols supported by Connect,
+// these field names must be included in header Access-Control-Allow-Headers
+// of the actual response.
+func AllowedHeaders() []string {
+	return []string{
+		"Content-Type",             // Required for Connect
+		"Connect-Protocol-Version", // Required for Connect
+		"Connect-Timeout-Ms",       // Optional for Connect
+		"Connect-Accept-Encoding",  // Future use for Connect
+		"Connect-Content-Encoding", // Future use for Connect
+		"Accept-Encoding",          // Future use for Connect
+		"Content-Encoding",         // Future use for Connect
+		"Grpc-Timeout",             // Required for gRPC-web
+		"X-Grpc-Web",               // Optional for gRPC-web
+		"X-User-Agent",             // Optional for gRPC-web
+	}
+}
+
+// ExposedHeaders returns the headers that scripts running in the browser are
+// permitted to see.
+//
+// To support cross-domain requests with the protocols supported by Connect,
+// these field names must be included in header Access-Control-Expose-Headers
+// of the actual response.
+//
+// Make sure to include any application-specific headers your browser client
+// should see. If your application uses trailers, they will be sent as header
+// fields with a `Trailer-` prefix for Connect unary RPCs - make sure to
+// expose them as well if you want them to be visible in all supported
+// protocols.
+func ExposedHeaders() []string {
+	return []string{
+		"Content-Encoding",         // Future use for Connect
+		"Connect-Content-Encoding", // Future use for Connect
+		"Grpc-Status",              // Required for gRPC-web header response
+		"Grpc-Message",             // Required for gRPC-web header response
+		"Grpc-Status-Details-Bin",  // Required for gRPC-web error details
+	}
+}