service

Documentation

Overview

Package service provides a server and an application-layer protocol for transmitting encoded Hermod units. It does not provide a client (at the moment).

You can use `service` by adding service endpoints to Hermod YAML files and then calling the generated Register<name>() function to register an endpoint handler. This will get called whenever a client requests that endpoint. Endpoints have fairly simple interfaces that work in a similar way to net/http, giving you a request and response object. Any errors returned within endpoint handlers are sent as encoded error objects to the client.

The package also provides a JWT-based authentication system. This allows clients to send a JWT along with their request, either as a query parameter in the initial session establishment request, or as a separate authentication packet at any time during the request. For more details see HermodAuthenticationConfig.

The server provided by the package is designed to be used to open a single WebSocket connection between a client and the server. All Hermod requests should be transmitted over that single connection to avoid the overhead of performing a WebSocket handshake. To that effect, you can either call StartServer to start a full HTTP server or you can use ServeConnection to manually perform WebSocket upgrades using your existing HTTP server, allowing you to use conventional HTTP endpoints at the same time as your Hermod endpoint.

Index

• func RegisterEndpoint(id uint16, handler func(request *Request, response *Response))
• func ServeConnection(config *HermodConfig, w http.ResponseWriter, r *http.Request)
• func StartServer(addr string, config *HermodConfig, httpConfig *HermodHTTPConfig) error
• type AuthAPI
  • func (api *AuthAPI) GetHydratedToken() (any, error)
  • func (api *AuthAPI) UpdateToken(token string) error
• type Endpoint
• type EndpointArgument
• type HermodAuthenticationConfig
  • func (config *HermodAuthenticationConfig) HydrateToken(token string) (any, *jwt.Token, error)
  • func (config *HermodAuthenticationConfig) ParseToken(token string) (*jwt.Token, error)
• type HermodConfig
• type HermodHTTPConfig
• type Request
• type Response
  • func (res *Response) Send(data *[]byte)
  • func (res *Response) SendError(err error)
• type Service

Functions

func RegisterEndpoint

func RegisterEndpoint(id uint16, handler func(request *Request, response *Response))

func ServeConnection

func ServeConnection(config *HermodConfig, w http.ResponseWriter, r *http.Request)

ServeConnection is made public to allow Hermod users to manually choose when to upgrade an HTTP connection to WebSocket/Hermod. Pass in the same HermodConfig as with service.StartServer, as well as http.ResponseWriter and http.Request, and ServeConnection will attempt to upgrade the HTTP connection to a WebSocket, and start responding to Hermod requests. ServeConnection will continue blocking until the WebSocket connection closes (e.g. if the underlying http.Request's context ends)

func StartServer

func StartServer(addr string, config *HermodConfig, httpConfig *HermodHTTPConfig) error

StartServer starts a full HTTP server which responds to WebSocket connections at HermodConfig.Path

Types

type AuthAPI

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

func (*AuthAPI) GetHydratedToken

func (api *AuthAPI) GetHydratedToken() (any, error)

func (*AuthAPI) UpdateToken

func (api *AuthAPI) UpdateToken(token string) error

type Endpoint

type Endpoint struct {
	Service *Service
	Path    string
	In      EndpointArgument
	Out     EndpointArgument
}

type EndpointArgument

type EndpointArgument struct {
	Unit     encoder.Unit
	Streamed bool
}

type HermodAuthenticationConfig

type HermodAuthenticationConfig struct {
	// SigningMethod must be defined. It's a function that returns true if the signing method of the token is what you
	// want it to be, and false if not.
	SigningMethod func(*jwt.Token) bool
	// either Secret or SecretProvider must be defined
	Secret []byte
	// SecretProvider doesn't need to verify the signing method, this is done automatically
	SecretProvider func(*jwt.Token) ([]byte, error)

	// TokenHydrator must be defined. It returns a custom type based on a map of pre-validated JWT claims.
	TokenHydrator func(jwt.MapClaims) (any, error)

	// UseCache determines whether to cache hydrated tokens. If false, only the raw JWT token will be saved for each
	// connection and must be rehydrated each time your code asks for it. If your hydrated value is unlikely to change during
	// a single connection, set this to true.
	UseCache bool
}

HermodAuthenticationConfig lets you set up and define parameters for Hermod's JWT-based authentication system. This is highly opinionated, and you don't have to use it! You can also use Hermod's authentication system outside of Hermod connections by using the public methods exposed by HermodAuthenticationConfig.

func (*HermodAuthenticationConfig) HydrateToken

func (config *HermodAuthenticationConfig) HydrateToken(token string) (any, *jwt.Token, error)

HydrateToken is a convenience method to parse and validate a JWT and to then 'hydrate' the token. It returns both the hydrated token and the raw parsed JWT. It will return an error if the JWT is not valid. The type of the hydrated token is inferred from the type parameter on HermodAuthenticationConfig.

func (*HermodAuthenticationConfig) ParseToken

func (config *HermodAuthenticationConfig) ParseToken(token string) (*jwt.Token, error)

ParseToken parses a JWT token, returning the parsed token object. It will use your specified secret and use the HermodAuthenticationConfig.SigningMethod function to determine whether the correct signing method is used. It does not check whether the token is valid. You can use jwt.Token.Valid to do this.

type HermodConfig

type HermodConfig struct {
	WSHandshakeTimeout time.Duration
	// AuthenticationConfig is optional, you can use it to enable a highly opinionated JWT-based authentication system.
	// If you want anything custom, you'll need to build it on your own for now!
	AuthenticationConfig *HermodAuthenticationConfig
}

type HermodHTTPConfig

type HermodHTTPConfig struct {
	// TLSConfig specifies an optional tls.Config to use with the HTTP server
	TLSConfig *tls.Config
	// UseWSS specifies whether to use a wss:// connection (WebSocket over HTTPS)
	UseWSS bool
	// CertFile and KeyFile are paths to the certificate files if UseWSS is true
	CertFile, KeyFile string

	// Path is the path at which Hermod should respond to WebSocket Upgrade requests. Requests to any other path
	// will result in a 404 response. Default value is "/hermod"
	Path string
}

type Request

type Request struct {
	Context context.Context
	Data    chan *[]byte
	Headers http.Header

	// Auth will be nil if authentication hasn't been set up in HermodConfig or if the WebSocket connection doesn't have
	// an authentication session assigned to it (either because there was no initial Authorization header or no Hermod
	// messages with the Authentication flag has been received)
	Auth *AuthAPI
}

type Response

type Response struct {
	// you're not supposed to write concurrently to a WebSocket connection
	sync.Mutex
	// contains filtered or unexported fields
}

func (*Response) Send

func (res *Response) Send(data *[]byte)

func (*Response) SendError

func (res *Response) SendError(err error)

type Service

type Service struct {
	Name string
}