prefab

README

Prefabricated gRPC Server and JSON/REST Gateway

Prefab is a library designed to streamline the setup of gRPC servers with a gRPC Gateway. It provides sensible defaults to get your server up and running with minimal boilerplate, while also offering configuration via environment variables, config files, or programmatic options.

Prefab includes a suite of plugins, adding capabilities such as authentication, authorization, logging, and templating.

✅ Features

• Quick setup: A production ready gRPC server in 6 lines of code.
• Multiplex gRPC and HTTP: Build hybrid monoliths serving both gRPC and HTTP on the same port.
• Serve static files: Serve static files for development or convenience.
• Pluggable: A plugin model provides easy customization and extensibility.
• Configurable: File, env, or functional options.
• Logging & errors: Request scoped field tracking, coded errors, stack traces, public/private error messages.
• Security: CSRF protection built-in and options for configuring CORS.
• Authn: Authenticate users with Google, Magic Links, or Email/Password.
• Authz: Use proto options to define access rules for RPC endpoints.
• Templates: Currently using standard go templates.

💡 Goals

gRPC is a powerful technology for building production-ready backends. Used with a gRPC Gateway and an entity-oriented RPC design, it can greatly simplify the construction and maintenance of web-facing REST-ish APIs.

Getting a project off the ground, however, often involves substantial boilerplate and lacks features common in HTTP frameworks such as Gin and Echo.

The purpose of prefab, therefore, is to expedite the development of gRPC web services, which can range from pure gRPC servers to hybrid monoliths that also serve HTTP. It offers optional plugins for authentication, access control, logging, email, and more, to further speed up the development of a minimally viable product, while always being production ready.

🚚 Key dependencies

• gRPC-go and gRPC Gateway
• Koanf for configuration
• Zap was chosen as default logging library.
• Gomail for sending email via SMTP.
• Standard Go templates

🚀 Quick Start

Given a GRPC service implementation, the following snippet will start a running server on localhost:5678 serving both GRPC requests and JSON rest, with the only constraint that the GRPC path bindings must be prefixed with /api/.

package main

import (
  "fmt"
  "github.com/dpup/prefab"
)

func main() {
	s := prefab.New()
	RegisterFooBarHandlerFromEndpoint(s.GatewayArgs())
	RegisterFooBarServer(s.ServiceRegistrar(), &foobarImpl{})
	if err := s.Start(); err != nil {
		fmt.Println(err)
	}
}

🔌 Plugins

• Plugin Model Overview
• Authentication
• Authorization
• Email
• Event Bus
• Storage
• Templates
• Upload

Plugin Model Overview

The base server is intended to have everything need to run a standalone service that multiplexes across a GRPC interface, a JSON/REST interface via the GRPC Gateway, and arbitrary HTTP handlers, for non-GRPC functionality. Additional functionality is exposed as plugins.

Plugins are essentially server scoped singletons which add functionality to the base server, expose functionality for other plugins, or extend other plugins.

As an example, the Magic Link Plugin extends the Auth Plugin to add authentication via email. It also depends on an Email Plugin for email sending, and a Template Plugin for rendering HTML emails.

It is intended that plugins can be have interchangable implementations to allow customization at various parts of the stack.

Plugin interfaces

Plugins can implement a number of discrete interfaces:

• prefab.Plugin : the required base interface which provides a name for each plugin.
• prefab.DependentPlugin : allows plugins to specify other plugins which they need to use.
• prefab.OptionalDependentPlugin : allows plugins to specify optional dependencies, which are not required, but must be initialized first.
• prefab.InitializablePlugin : allows plugins to be initialized in dependency order, allowing for more control of setup.
• prefab.OptionProvider : allows plugins to modify the server behavior, add services, or handlers. See prefab.Option for full functionality.

By convention, plugins should be created by a Plugin function. If the plugin is intended to be used by other plugins, it's name should be exported as PluginName. For example, gpt.Plugin(...) and gpt.PluginName.

Explore the GoDoc and examples to learn how to use each prefab plugin.

Authentication

Prefab offers a number of authentication plugins that can speed up development of logged in experiences.

Core functionality is provided by auth.Plugin(), however at least one auth provider should be registered. The following providers are currently included.

• Google SSO
• Magiclink passwordless login
• Pasword auth
• Fake auth
• API Key

Login is initiated through the auth.Login() RPC or the /api/auth/login endpoint.

Clients can access identity information through the auth.Identity() RPC or the /api/auth/me endpoint.

Authentication can be performed through bearer tokens or cookies.

Importantly, the authentication plugins make an authenticated identity available, however, it does not handle authorization. That must be handled by application code.

Configuration

Functional Option	Configuration Key	Description
WithSigningKey	auth.signingKey	Key used when signing JWT tokens
WithExpiration	auth.expiration	Expiry duration for which JWT tokens
WithBlocklist	-	Customize blocklist implementation

Invalidation

By default, Prefab's identity tokens are valid until they expire. Logging out will clear the cookie, but if the token was copied or compromised it can still be used to identify the user. If the token is used for accessing sensitive resources, then it is recommended that a short lifetime be configured via the auth.expiration config or auth.WithExpiration option.

If you wish to utilize long-lived identity tokens, but need a way to ensure they are revoked, then you can initialize your server with a Storage Plugin and the Auth Plugin with persist blocked tokens. Everytime a token is validated, the blocklist will be checked, which will introduce some latency.

s := prefab.New(
  ...
  prefab.WithPlugin(storage.Plugin(store)),
  prefab.WithPlugin(auth.Plugin()),
  )),
  ...
)

If you wish you implement your own Blocklist, then you can do so like so:

s := prefab.New(
  ...
  prefab.WithPlugin(auth.Plugin(
    auth.WithBlocklist(auth.NewBlocklist(store)),
  )),
  ...
)

Authorization

Building on top of the authentication plugin, authz allows for access controls to be configured at the RPC level in the protocol buffer definitions.

For now, see the examples for more details on how it works.

Storage

Prefab includes a simple Storage interface, primarily for use within plugins, but also for simple applications. The interface exposes Create, Read, Update, Upsert, Delete, List, and Exists (CRUUDLE) methods and can be backed by a memory store, filesystems, RDS, or NoSQL databases.

Entities are modeled as Go structs which expose a PK() method. The internal storage representation is implementation specific, however JSON is a common default, and as such List operations may not be performant for many situations.

Included implementations:

In-Memory: Stores data in simple Go maps.

SQLite3: SQLite backed storage. Explicitly initialized models are stored in their own table, with a prefab_ prefix. Uninitialized models are stored in prefab_default indexed by ID and EntityType.

Postgres: Postgres backed storage. Explicitly initialized models are stored in their own table, uninitialized models are stored in a default table. There is an option to have tables automatically created.

🔐 Security

• CSRF Protection: header for XHR and double submit cookies for form posts.
• Security headers: X-Frames-Options, HTTP Strict Transport Security (HSTS), Cross origin requests (CORS), Referrer Policy etc.

CSRF Protection

CSRF Protection is handled by middleware and is controlled by an option on the method descriptor.

Possible values are "on", "off", and "auto", where "auto is the default.

• "on" means CSRF protection is always needed.
• "off" means it is never needed.
• "auto" indicates CSRF protection is needed unless the HTTP method is GET, HEAD, or OPTIONS.

rpc Get(Request) returns (Response) {
  option (csrf_mode) = "on";
  option (google.api.http) = {
    get: "/get"
  };
}

CSRF Protection comes in two forms, an X-CSRF-Protection header, which can be set on XHR requests, or a signed double-submit cookie, which are to be used for form posts and full-page navigations.

For the double-submit method, the CSRF Token can be requested from the /api/meta/config endpoint. It is valid for 6 hours, querying the config endpoint will extend the expiration. The token should be passed to the server in a csrf-token query param.

The token can also be found in the pf-ct cookie. If you are using the cookie instead of requesting the token from the config endpoint then your server code will need to call prefab.SendCSRFToken(ctx, signingKey) at somepoint in the user journey to ensure the cookie is set.

Example XHR:

fetch("/api/users/154", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "X-CSRF-Protection": 1,
  },
  credentials: "include",
  body: JSON.stringify({
    name: "Frodo Baggins",
  }),
});

Security Headers

XFrameOptions, HSTS, and CORS can be configured via the config file or using prefab.WithSecurityHeaders.

Example configuration that force HTTPS and allows cross-origin requests:

server:
  security:
    # Prevent iframing.
    xFrameOptions: DENY

    # Force HTTPS
    hstsExpiration: 31536000s
    hstsIncludeSubdomains: true
    hstsPreload: true

    # Allow CORS from a static app and a single 3rd party site.
    corsOrigins:
      - https://app.example.com
      - https://plugin.vendor.com
    corsAllowedMethods:
      - GET
      - POST
      - PUT
    corsAllowedHeaders:
      - x-csrf-protection
    corsAllowCredentials: true
    corsMaxAge: 72h

Documentation

Overview

Package prefab provides a library to streamline the initialization and configuration of a typical hybrid web server, which can handle GRPC, JSON RPC, and regular HTTP handlers.

Index

• Constants
• Variables
• func RegisterMetaServiceHandler(ctx context.Context, mux *runtime.ServeMux, conn *grpc.ClientConn) error
• func RegisterMetaServiceHandlerClient(ctx context.Context, mux *runtime.ServeMux, client MetaServiceClient) error
• func RegisterMetaServiceHandlerFromEndpoint(ctx context.Context, mux *runtime.ServeMux, endpoint string, ...) (err error)
• func RegisterMetaServiceHandlerServer(ctx context.Context, mux *runtime.ServeMux, server MetaServiceServer) error
• func RegisterMetaServiceServer(s grpc.ServiceRegistrar, srv MetaServiceServer)
• func SendCSRFToken(ctx context.Context, signingKey []byte) string
• func VerifyCSRF(ctx context.Context, signingKey []byte) error
• type ClientConfigRequest
  • func (*ClientConfigRequest) Descriptor() ([]byte, []int)
  • func (*ClientConfigRequest) ProtoMessage()
  • func (x *ClientConfigRequest) ProtoReflect() protoreflect.Message
  • func (x *ClientConfigRequest) Reset()
  • func (x *ClientConfigRequest) String() string
• type ClientConfigResponse
  • func (*ClientConfigResponse) Descriptor() ([]byte, []int)
  • func (x *ClientConfigResponse) GetConfigs() map[string]string
  • func (x *ClientConfigResponse) GetCsrfToken() string
  • func (*ClientConfigResponse) ProtoMessage()
  • func (x *ClientConfigResponse) ProtoReflect() protoreflect.Message
  • func (x *ClientConfigResponse) Reset()
  • func (x *ClientConfigResponse) String() string
• type ConfigInjector
• type CustomErrorResponse
  • func (*CustomErrorResponse) Descriptor() ([]byte, []int)
  • func (x *CustomErrorResponse) GetCode() int32
  • func (x *CustomErrorResponse) GetCodeName() string
  • func (x *CustomErrorResponse) GetDetails() []*anypb.Any
  • func (x *CustomErrorResponse) GetMessage() string
  • func (*CustomErrorResponse) ProtoMessage()
  • func (x *CustomErrorResponse) ProtoReflect() protoreflect.Message
  • func (x *CustomErrorResponse) Reset()
  • func (x *CustomErrorResponse) String() string
• type DependentPlugin
• type InitializablePlugin
• type JSONHandler
• type MetaServiceClient
  • func NewMetaServiceClient(cc grpc.ClientConnInterface) MetaServiceClient
• type MetaServiceServer
• type OptionProvider
• type OptionalDependentPlugin
• type Plugin
• type Registry
  • func (r *Registry) Get(key string) Plugin
  • func (r *Registry) Init(ctx context.Context) error
  • func (r *Registry) Register(plugin Plugin)
  • func (r *Registry) Shutdown(ctx context.Context) error
• type SecurityHeaders
  • func (s *SecurityHeaders) Apply(w http.ResponseWriter, r *http.Request) error
• type Server
  • func New(opts ...ServerOption) *Server
  • func (s *Server) GRPCServerForReflection() reflection.GRPCServer
  • func (s *Server) GatewayArgs() (ctx context.Context, mux *runtime.ServeMux, endpoint string, ...)
  • func (s *Server) ServiceRegistrar() grpc.ServiceRegistrar
  • func (s *Server) Shutdown() error
  • func (s *Server) Start() error
• type ServerOption
  • func WithCRSFSigningKey(signingKey string) ServerOption
  • func WithClientConfig(key, value string) ServerOption
  • func WithContext(ctx context.Context) ServerOption
  • func WithGRPCGateway(...) ServerOption
  • func WithGRPCInterceptor(interceptor grpc.UnaryServerInterceptor) ServerOption
  • func WithGRPCReflection() ServerOption
  • func WithGRPCService(desc *grpc.ServiceDesc, impl any) ServerOption
  • func WithHTTPHandler(prefix string, h http.Handler) ServerOption
  • func WithHTTPHandlerFunc(prefix string, h func(http.ResponseWriter, *http.Request)) ServerOption
  • func WithHost(host string) ServerOption
  • func WithIncomingHeaders(headers ...string) ServerOption
  • func WithJSONHandler(prefix string, h JSONHandler) ServerOption
  • func WithMaxRecvMsgSize(maxMsgSizeBytes int) ServerOption
  • func WithPlugin(p Plugin) ServerOption
  • func WithPort(port int) ServerOption
  • func WithRequestConfig(injector ConfigInjector) ServerOption
  • func WithSecurityHeaders(headers *SecurityHeaders) ServerOption
  • func WithStaticFiles(prefix, dir string) ServerOption
  • func WithTLS(certFile, keyFile string) ServerOption
• type ShutdownPlugin
• type UnimplementedMetaServiceServer
  • func (UnimplementedMetaServiceServer) ClientConfig(context.Context, *ClientConfigRequest) (*ClientConfigResponse, error)
• type UnsafeMetaServiceServer
• type XFramesOptions

Constants

const ConfigFile = "prefab.yaml"

Filename of the standard configuration file.

const (
	MetaService_ClientConfig_FullMethodName = "/prefab.MetaService/ClientConfig"
)

Variables

var Config = koanf.New(".")

Config is a global koanf instance used to access application level configuration options.

var (
	// Whether CSRF verification should be handled by a GRPC Interceptor.
	//
	// Possible values are "on", "off", and "auto".
	//
	// "auto" will enable CSRF checks unless a safe HTTP method is detected (GET,
	// HEAD, and OPTIONS) from the GRPC Gateway. If no HTTP method is detected, it
	// is assumed that the request came via a non-browser client and CSRF checks
	// are disabled.
	//
	// Defaults to "auto".
	//
	// optional string csrf_mode = 50001;
	E_CsrfMode = &file_server_proto_extTypes[0]
)

Extension fields to descriptorpb.MethodOptions.

var (
	// HSTS requires a minimum expiration of 1 year for preload.
	ErrBadHSTSExpiration = errors.NewC("prefab: HSTS preload requires expiration of at least 1 year", codes.FailedPrecondition)
)

var File_metaservice_proto protoreflect.FileDescriptor

var File_server_proto protoreflect.FileDescriptor

var JSONMarshalOptions = protojson.MarshalOptions{
	Multiline:       true,
	Indent:          "  ",
	EmitUnpopulated: true,
	UseProtoNames:   false,
}

Options passed to runtime.JSONPb when building the server.

var MetaService_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "prefab.MetaService",
	HandlerType: (*MetaServiceServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "ClientConfig",
			Handler:    _MetaService_ClientConfig_Handler,
		},
	},
	Streams:  []grpc.StreamDesc{},
	Metadata: "metaservice.proto",
}

MetaService_ServiceDesc is the grpc.ServiceDesc for MetaService service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

Functions

func RegisterMetaServiceHandler

func RegisterMetaServiceHandler(ctx context.Context, mux *runtime.ServeMux, conn *grpc.ClientConn) error

RegisterMetaServiceHandler registers the http handlers for service MetaService to "mux". The handlers forward requests to the grpc endpoint over "conn".

func RegisterMetaServiceHandlerClient

func RegisterMetaServiceHandlerClient(ctx context.Context, mux *runtime.ServeMux, client MetaServiceClient) error

RegisterMetaServiceHandlerClient registers the http handlers for service MetaService to "mux". The handlers forward requests to the grpc endpoint over the given implementation of "MetaServiceClient". Note: the gRPC framework executes interceptors within the gRPC handler. If the passed in "MetaServiceClient" doesn't go through the normal gRPC flow (creating a gRPC client etc.) then it will be up to the passed in "MetaServiceClient" to call the correct interceptors. This client ignores the HTTP middlewares.

func RegisterMetaServiceHandlerFromEndpoint

func RegisterMetaServiceHandlerFromEndpoint(ctx context.Context, mux *runtime.ServeMux, endpoint string, opts []grpc.DialOption) (err error)

RegisterMetaServiceHandlerFromEndpoint is same as RegisterMetaServiceHandler but automatically dials to "endpoint" and closes the connection when "ctx" gets done.

func RegisterMetaServiceHandlerServer

func RegisterMetaServiceHandlerServer(ctx context.Context, mux *runtime.ServeMux, server MetaServiceServer) error

RegisterMetaServiceHandlerServer registers the http handlers for service MetaService to "mux". UnaryRPC :call MetaServiceServer directly. StreamingRPC :currently unsupported pending https://github.com/grpc/grpc-go/issues/906. Note that using this registration option will cause many gRPC library features to stop working. Consider using RegisterMetaServiceHandlerFromEndpoint instead. GRPC interceptors will not work for this type of registration. To use interceptors, you must use the "runtime.WithMiddlewares" option in the "runtime.NewServeMux" call.

func RegisterMetaServiceServer

func RegisterMetaServiceServer(s grpc.ServiceRegistrar, srv MetaServiceServer)

func SendCSRFToken

func SendCSRFToken(ctx context.Context, signingKey []byte) string

SendCSRFToken sends a CSRF token in the response cookies and returns the value for use in the response body.

func VerifyCSRF

func VerifyCSRF(ctx context.Context, signingKey []byte) error

VerifyCSRF checks the incoming request for a CSRF token. It looks for the token in the query params and cookies, and verifies that they match. If the token is missing or invalid, an error is returned.

Types

type ClientConfigRequest

type ClientConfigRequest struct {
	// contains filtered or unexported fields
}

Empty request object.

func (*ClientConfigRequest) Descriptor

func (*ClientConfigRequest) Descriptor() ([]byte, []int)

Deprecated: Use ClientConfigRequest.ProtoReflect.Descriptor instead.

func (*ClientConfigRequest) ProtoMessage

func (*ClientConfigRequest) ProtoMessage()

func (*ClientConfigRequest) ProtoReflect

func (x *ClientConfigRequest) ProtoReflect() protoreflect.Message

func (*ClientConfigRequest) Reset

func (x *ClientConfigRequest) Reset()

func (*ClientConfigRequest) String

func (x *ClientConfigRequest) String() string

type ClientConfigResponse

type ClientConfigResponse struct {

	// A map of key-value pairs configured by available plugins, for example
	// auth.google.client_id.
	Configs map[string]string `` /* 141-byte string literal not displayed */
	// Token that should be used in non-XHR requests to avoid cross-site request
	// forgery attacks.
	CsrfToken string `protobuf:"bytes,2,opt,name=csrf_token,json=csrfToken,proto3" json:"csrf_token,omitempty"`
	// contains filtered or unexported fields
}

Configuration information to help clients facilitate interactions with the API server.

func (*ClientConfigResponse) Descriptor

func (*ClientConfigResponse) Descriptor() ([]byte, []int)

Deprecated: Use ClientConfigResponse.ProtoReflect.Descriptor instead.

func (*ClientConfigResponse) GetConfigs

func (x *ClientConfigResponse) GetConfigs() map[string]string

func (*ClientConfigResponse) GetCsrfToken

func (x *ClientConfigResponse) GetCsrfToken() string

func (*ClientConfigResponse) ProtoMessage

func (*ClientConfigResponse) ProtoMessage()

func (*ClientConfigResponse) ProtoReflect

func (x *ClientConfigResponse) ProtoReflect() protoreflect.Message

func (*ClientConfigResponse) Reset

func (x *ClientConfigResponse) Reset()

func (*ClientConfigResponse) String

func (x *ClientConfigResponse) String() string

type ConfigInjector

type ConfigInjector func(context.Context) context.Context

ConfigInjector is a function that injects configuration into a context.

type CustomErrorResponse

type CustomErrorResponse struct {
	Code     int32        `protobuf:"varint,1,opt,name=code,proto3" json:"code,omitempty"`
	CodeName string       `protobuf:"bytes,2,opt,name=code_name,json=codeName,proto3" json:"code_name,omitempty"`
	Message  string       `protobuf:"bytes,3,opt,name=message,proto3" json:"message,omitempty"`
	Details  []*anypb.Any `protobuf:"bytes,4,rep,name=details,proto3" json:"details,omitempty"`
	// contains filtered or unexported fields
}

Overrides the default error gateway error response to include a code_name for convenience.

func (*CustomErrorResponse) Descriptor

func (*CustomErrorResponse) Descriptor() ([]byte, []int)

Deprecated: Use CustomErrorResponse.ProtoReflect.Descriptor instead.

func (*CustomErrorResponse) GetCode

func (x *CustomErrorResponse) GetCode() int32

func (*CustomErrorResponse) GetCodeName

func (x *CustomErrorResponse) GetCodeName() string

func (*CustomErrorResponse) GetDetails

func (x *CustomErrorResponse) GetDetails() []*anypb.Any

func (*CustomErrorResponse) GetMessage

func (x *CustomErrorResponse) GetMessage() string

func (*CustomErrorResponse) ProtoMessage

func (*CustomErrorResponse) ProtoMessage()

func (*CustomErrorResponse) ProtoReflect

func (x *CustomErrorResponse) ProtoReflect() protoreflect.Message

func (*CustomErrorResponse) Reset

func (x *CustomErrorResponse) Reset()

func (*CustomErrorResponse) String

func (x *CustomErrorResponse) String() string

type DependentPlugin

type DependentPlugin interface {
	// Deps returns the names for plugins which this plugin depends on.
	Deps() []string
}

Implemented if plugin depends on other plugins.

type InitializablePlugin

type InitializablePlugin interface {
	// Init the plugin. Will be called in dependency order.
	Init(ctx context.Context, r *Registry) error
}

Implemented if the plugin needs to be initialized outside construction.

type JSONHandler

type JSONHandler func(req *http.Request) (any, error)

JSONHandler are regular HTTP handlers that return a response that should be encoded in a similar fashion to a gRPC Gateway response.

If the return value is a proto.Message, it will be marshaled using the same JSON marshaler as the gRPC Gateway.

type MetaServiceClient

type MetaServiceClient interface {
	// ClientConfig returns configuration information that is required for clients
	// to interact with the server in various ways. All data is safe to be served
	// to unauthenticatd clients.
	ClientConfig(ctx context.Context, in *ClientConfigRequest, opts ...grpc.CallOption) (*ClientConfigResponse, error)
}

MetaServiceClient is the client API for MetaService service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

func NewMetaServiceClient

func NewMetaServiceClient(cc grpc.ClientConnInterface) MetaServiceClient

type MetaServiceServer

type MetaServiceServer interface {
	// ClientConfig returns configuration information that is required for clients
	// to interact with the server in various ways. All data is safe to be served
	// to unauthenticatd clients.
	ClientConfig(context.Context, *ClientConfigRequest) (*ClientConfigResponse, error)
	// contains filtered or unexported methods
}

MetaServiceServer is the server API for MetaService service. All implementations must embed UnimplementedMetaServiceServer for forward compatibility.

type OptionProvider

type OptionProvider interface {
	ServerOptions() []ServerOption
}

OptionProvider can be implemented by plugins to augment the server at build time.

type OptionalDependentPlugin

type OptionalDependentPlugin interface {
	// OptDeps returns the names for plugins which this plugin optionally depends on.
	OptDeps() []string
}

Implemented if plugin has optional dependencies, which should be initialized before the plugin, but are not required.

type Plugin

type Plugin interface {
	// Name of the plugin, used for querying and dependency resolution.
	Name() string
}

The base plugin interface.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages plugins and their dependencies.

func (*Registry) Get

func (r *Registry) Get(key string) Plugin

Get a plugin.

func (*Registry) Init

func (r *Registry) Init(ctx context.Context) error

Init all plugins in the Registry. Plugins will be visited in dependency order.

func (*Registry) Register

func (r *Registry) Register(plugin Plugin)

Register a plugin.

func (*Registry) Shutdown

func (r *Registry) Shutdown(ctx context.Context) error

Shutdown any plugins that implement the shutdown interface.

type SecurityHeaders

type SecurityHeaders struct {
	// X-Frame-Options controls whether the browser should allow the page to be
	// rendered in a frame or iframe.
	XFramesOptions XFramesOptions

	// Strict-Transport-Security (HSTS) tells the browser to always use HTTPS
	// when connecting to the site.
	HSTSExpiration        time.Duration
	HSTSIncludeSubdomains bool
	HSTSPreload           bool

	// Access-Control headers define which origins are allowed to access the
	// resource and what methods are allowed.
	// TODO: Should this allow for patterns instead of only exact origin matches?
	CORSOrigins          []string
	CORSAllowMethods     []string
	CORSAllowHeaders     []string
	CORSExposeHeaders    []string
	CORSAllowCredentials bool
	CORSMaxAge           time.Duration
	// contains filtered or unexported fields
}

SecurityHeaders contains the security headers that should be set on HTTP responses.

func (*SecurityHeaders) Apply

func (s *SecurityHeaders) Apply(w http.ResponseWriter, r *http.Request) error

Apply the security headers to the given response.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server wraps a HTTP server, a GRPC server, and a GRPC Gateway.

Usage:

server := server.New(opts...)
debugservice.RegisterDebugServiceHandlerFromEndpoint(server.GatewayArgs())
debugservice.RegisterDebugServiceServer(server.ServiceRegistrar(), &impl{})
server.Start()

See examples/simpleserver.

func New

func New(opts ...ServerOption) *Server

New returns a new server.

func (*Server) GRPCServerForReflection

func (s *Server) GRPCServerForReflection() reflection.GRPCServer

GRPCServerForReflection returns the GRPC Server for use with reflection.

func (*Server) GatewayArgs

func (s *Server) GatewayArgs() (ctx context.Context, mux *runtime.ServeMux, endpoint string, opts []grpc.DialOption)

GatewayArgs is used when registering a gateway handler.

For example, if you have DebugService:

debugservice.RegisterDebugServiceHandlerFromEndpoint(server.GatewayArgs())

func (*Server) ServiceRegistrar

func (s *Server) ServiceRegistrar() grpc.ServiceRegistrar

GRPCServer returns the GRPC Service Registrar for use with service implementations.

For example, if you have DebugService:

debugservice.RegisterDebugServiceServer(server.ServiceRegistrar(), &debugServiceImpl{})

func (*Server) Shutdown

func (s *Server) Shutdown() error

Shutdown gracefully shuts down the server with a 2s timeout.

func (*Server) Start

func (s *Server) Start() error

Start serving requests. Blocks until Shutdown is called.

type ServerOption

type ServerOption func(*builder)

ServerOptions customize the configuration and operation of the GRPC server.

func WithCRSFSigningKey

func WithCRSFSigningKey(signingKey string) ServerOption

WithCRSFSigningKey sets the key used to sign CSRF tokens.

Config key: `server.csrfSigningKey`.

func WithClientConfig

func WithClientConfig(key, value string) ServerOption

WithClientConfig adds a key value pair which will be made available to the client via the metaservice.

func WithContext

func WithContext(ctx context.Context) ServerOption

WithContext sets the base context for the server. This context will be used for all requests and can be used to inject values into the context.

func WithGRPCGateway

func WithGRPCGateway(fn func(ctx context.Context, mux *runtime.ServeMux, endpoint string, opts []grpc.DialOption) error) ServerOption

WithGRPCGateway registers a GRPC gateway handler.

Example:

WithGRPCGateway(debugservice.RegisterDebugServiceHandlerFromEndpoint)

func WithGRPCInterceptor

func WithGRPCInterceptor(interceptor grpc.UnaryServerInterceptor) ServerOption

WithGRPCInterceptor configures GRPC Unary Interceptors. They will be executed in the order they were added.

func WithGRPCReflection

func WithGRPCReflection() ServerOption

WithGRPCReflection registers the GRPC reflection service.

func WithGRPCService

func WithGRPCService(desc *grpc.ServiceDesc, impl any) ServerOption

WithGRPCService registers a GRPC service handler.

func WithHTTPHandler

func WithHTTPHandler(prefix string, h http.Handler) ServerOption

WithHTTPHandler adds an HTTP handler.

func WithHTTPHandlerFunc

func WithHTTPHandlerFunc(prefix string, h func(http.ResponseWriter, *http.Request)) ServerOption

WithHTTPHandlerFunc adds an HTTP handler function.

func WithHost

func WithHost(host string) ServerOption

WithHost configures the hostname or IP the server will listen on.

Config key: `server.host`.

func WithIncomingHeaders

func WithIncomingHeaders(headers ...string) ServerOption

WithIncomingHeaders specifies a safe-list of headers that can be forwarded via gRPC metadata with the `prefab` prefix. Headers that are allowed by the CORS security config are automatically added to this list, see WithSecurityHeaders.

Config key: `server.incomingHeaders`.

func WithJSONHandler

func WithJSONHandler(prefix string, h JSONHandler) ServerOption

WithJSONHandler adds a HTTP handler which returns JSON, serialized in a consistent way to gRPC gateway responses.

func WithMaxRecvMsgSize

func WithMaxRecvMsgSize(maxMsgSizeBytes int) ServerOption

WithMaxRecvMsgSize sets the maximum GRPC message size. Default is 4Mb.

Config key: `server.maxMsgSizeBytes`.

func WithPlugin

func WithPlugin(p Plugin) ServerOption

WithPlugin registers a plugin with the server's registry. Plugins will be initialized at server start. If the Plugin implements `OptionProvider` then additional server options can be configured for the server.

func WithPort

func WithPort(port int) ServerOption

WithPort configures the port the server will listen on.

Config key: `server.port`.

func WithRequestConfig

func WithRequestConfig(injector ConfigInjector) ServerOption

WithRequestConfig adds a ConfigInjector to the server. The injector will be called for every request and can be used to inject request scoped configuration into the context.

func WithSecurityHeaders

func WithSecurityHeaders(headers *SecurityHeaders) ServerOption

WithSecurityHeaders sets the security headers that should be set on HTTP responses.

Config keys: - `server.security.xFramesOptions` - `server.security.hstsExpiration` - `server.security.hstsIncludeSubdomains` - `server.security.hstsPreload` - `server.security.corsOrigins` - `server.security.corsAllowMethods` - `server.security.corsAllowHeaders` - `server.security.corsExposeHeaders` - `server.security.corsAllowCredentials` - `server.security.corsMaxAge`.

func WithStaticFiles

func WithStaticFiles(prefix, dir string) ServerOption

WithStaticFileServer configures the server to serve static files from disk for HTTP requests that match the given prefix.

func WithTLS

func WithTLS(certFile, keyFile string) ServerOption

WithTLS configures the server to allow traffic via TLS using the provided cert. If not called server will use HTTP/H2C.

Config keys: `server.tls.certFile`, `server.tls.keyFile`.

type ShutdownPlugin

type ShutdownPlugin interface {
	// Shutdown the plugin.
	Shutdown(ctx context.Context) error
}

Implemented if the plugin needs to be shutdown.

type UnimplementedMetaServiceServer

type UnimplementedMetaServiceServer struct{}

UnimplementedMetaServiceServer must be embedded to have forward compatible implementations.

NOTE: this should be embedded by value instead of pointer to avoid a nil pointer dereference when methods are called.

func (UnimplementedMetaServiceServer) ClientConfig

func (UnimplementedMetaServiceServer) ClientConfig(context.Context, *ClientConfigRequest) (*ClientConfigResponse, error)

type UnsafeMetaServiceServer

type UnsafeMetaServiceServer interface {
	// contains filtered or unexported methods
}

UnsafeMetaServiceServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to MetaServiceServer will result in compilation errors.

type XFramesOptions

type XFramesOptions string

const (
	XFramesOptionsNone       XFramesOptions = ""
	XFramesOptionsDeny       XFramesOptions = "DENY"
	XFramesOptionsSameOrigin XFramesOptions = "SAMEORIGIN"
)