cors

README

cors

connectrpc.com/cors simplifies Cross-Origin Resource Sharing (CORS) for Connect servers. CORS is usually required for the Connect and gRPC-Web protocols to work correctly in web browsers.

For background, more details, and best practices, see Connect's CORS documentation. For more on Connect, see the announcement blog post, the documentation on connectrpc.com (especially the Getting Started guide for Go), the demo service, or the protocol specification.

Example

This package should work with any CORS implementation. As an example, we'll use it with github.com/rs/cors.

import (
  connectcors "connectrpc.com/cors"
  "github.com/rs/cors"
)

// withCORS adds CORS support to a Connect HTTP handler.
func withCORS(connectHandler http.Handler) http.Handler {
  c := cors.New(cors.Options{
    AllowedOrigins: []string{"https://acme.com"}, // replace with your domain
    AllowedMethods: connectcors.AllowedMethods(),
    AllowedHeaders: connectcors.AllowedHeaders(),
    ExposedHeaders: connectcors.ExposedHeaders(),
    MaxAge: 7200, // 2 hours in seconds
  })
  return c.Handler(connectHandler)
}

Ecosystem

• connect-go: the Go implementation of Connect's RPC runtime
• examples-go: service powering demo.connectrpc.com, including bidi streaming
• grpchealth: gRPC-compatible health checks
• grpcreflect: gRPC-compatible server reflection
• authn: pluggable authentication for Connect servers
• connect-es: Type-safe APIs with Protobuf and TypeScript
• conformance: Connect, gRPC, and gRPC-Web interoperability tests

Status: Unstable

This module isn't stable yet, but it's fairly small — we expect to reach a stable release quickly.

It supports the three most recent major releases of Go. Keep in mind that only the last two releases receive security patches.

Within those parameters, cors follows semantic versioning. We will not make breaking changes in the 1.x series of releases.

Legal

Offered under the Apache 2 license.

Documentation

Overview

Package cors provides helpers to configure cross-origin resource sharing (CORS) for Connect servers.

Index

• func AllowedHeaders() []string
• func AllowedMethods() []string
• func ExposedHeaders() []string

Functions

func AllowedHeaders

func AllowedHeaders() []string

AllowedHeaders returns the headers that scripts running in the browser send when making RPC requests. To support cross-domain requests with the protocols supported by Connect, these field names must be included in the Access-Control-Allow-Headers header of the preflight response.

When configuring CORS, make sure to also include any application-specific headers your server expects to receive from the browser.

func AllowedMethods

func AllowedMethods() []string

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 ExposedHeaders

func ExposedHeaders() []string

ExposedHeaders returns the headers that scripts running in the browser expect to access when receiving RPC responses. To support cross-domain requests with the protocols supported by Connect, these field names must be included in the Access-Control-Expose-Headers header of the actual response.

When configuring CORS, make sure to also include any application-specific headers your server expects to send to the browser. If your application uses trailers, they will be sent as headers with a `Trailer-` prefix for unary Connect RPCs - make sure to expose them!