funcie

Documentation

Index

• Variables
• func CloseOrLog(name string, c Closable)
• func ConfigureLogging()
• func IsRunningWithLambda() bool
• func MustDeserialize[T any](b []byte) T
• func MustSerialize(v interface{}) []byte
• func UnmarshalMessagePayload[MessageType MessageBase[T], T any](message *Message) (*MessageType, error)
• func UnmarshalResponsePayload[ResponseType ResponseBase[T], T any](response *Response) (*ResponseType, error)
• type Application
  • func NewApplication(name string, endpoint Endpoint) *Application
  • func (a *Application) String() string
• type ApplicationRegistry
• type Closable
• type Consumer
• type Endpoint
  • func MustNewEndpointFromAddress(address string) Endpoint
  • func NewEndpoint(scheme string, host string, port int) Endpoint
  • func NewEndpointFromAddress(address string) (Endpoint, error)
  • func (e Endpoint) String() string
• type Handler
• type Message
  • func MarshalMessagePayload[MessageType MessageBase[T], T any](message MessageType) (*Message, error)
  • func NewMessage(application string, kind MessageKind, payload []byte) *Message
• type MessageBase
  • func NewMessageWithPayload[T any](application string, kind MessageKind, payload T) *MessageBase[T]
  • func (m *MessageBase[T]) String() string
• type MessageKind
• type Pinger
• type ProxyError
  • func NewProxyError(message string) *ProxyError
  • func NewProxyErrorFromError(err error) *ProxyError
  • func (e *ProxyError) Error() string
  • func (e *ProxyError) MarshalJSON() ([]byte, error)
  • func (e *ProxyError) UnmarshalJSON(data []byte) error
• type Publisher
• type Response
  • func MarshalResponsePayload[T any](response *ResponseBase[T]) (*Response, error)
  • func NewResponse(id string, data []byte, error error) *Response
• type ResponseBase
  • func NewResponseWithPayload[T any](id string, payload *T, error error) *ResponseBase[T]
• type Tunnel
  • func NewLambdaTunnel(applicationId string, handler interface{}, publisher Publisher, ...) Tunnel

Variables

var ErrApplicationNotFound = errors.New("application not found")

ErrApplicationNotFound is returned when an application is not found.

var ErrNoActiveConsumer = errors.New("no consumer is active on this tunnel")

ErrNoActiveConsumer is returned when a consumer is not active on a tunnel.

var ErrPubSubChannelClosed = fmt.Errorf("pubsub channel closed")

Functions

func CloseOrLog

func CloseOrLog(name string, c Closable)

CloseOrLog closes the given closable, logging any errors (but continuing execution).

func ConfigureLogging

func ConfigureLogging()

ConfigureLogging configures slog to log to stdout at the given level. If FUNCIE_LOG_LEVEL is set, it will be used as the log level. Otherwise, the default is Info.

func IsRunningWithLambda

func IsRunningWithLambda() bool

IsRunningWithLambda returns true if the current process is running in AWS Lambda.

func MustDeserialize

func MustDeserialize[T any](b []byte) T

MustDeserialize deserializes the given JSON to the given type, or panics if it fails.

func MustSerialize

func MustSerialize(v interface{}) []byte

MustSerialize serializes the given value to JSON, or panics if it fails.

func UnmarshalMessagePayload

func UnmarshalMessagePayload[MessageType MessageBase[T], T any](message *Message) (*MessageType, error)

UnmarshalMessagePayload unmarshals the payload of the given message into the given payload type.

func UnmarshalResponsePayload

func UnmarshalResponsePayload[ResponseType ResponseBase[T], T any](response *Response) (*ResponseType, error)

UnmarshalResponsePayload unmarshals the payload of the given response into the given payload type.

Types

type Application

type Application struct {
	// Name is the name of the application.
	Name string `json:"name"`
	// Endpoint is the address to send requests to.
	Endpoint Endpoint `json:"endpoint"`
}

Application represents a registered application that can have requests routed to it.

func NewApplication

func NewApplication(name string, endpoint Endpoint) *Application

NewApplication creates a new Application with the given name and endpoint.

func (*Application) String

func (a *Application) String() string

String returns a string representation of the application.

type ApplicationRegistry

type ApplicationRegistry interface {
	// Register registers the given application.
	Register(ctx context.Context, application *Application) error
	// Unregister unregisters the application with the given name.
	Unregister(ctx context.Context, applicationName string) error
	// GetApplication gets the application with the given name.
	// If no application is registered with the given name, ErrApplicationNotFound is returned.
	GetApplication(ctx context.Context, applicationName string) (*Application, error)
}

ApplicationRegistry is a service that can register and unregister applications.

type Closable

type Closable interface {
	Close() error
}

type Consumer

type Consumer interface {
	Connect(ctx context.Context) error
	Consume(ctx context.Context) error
	Subscribe(ctx context.Context, applicationId string, handler Handler) error
	Unsubscribe(ctx context.Context, applicationId string) error
}

Consumer represents a consumer of a synchronous tunnel that can be used to receive messages from a publisher and send a response.

type Endpoint

type Endpoint struct {
	// Scheme is the protocol scheme of the endpoint.
	// This is usually "http" or "https".
	Scheme string `json:"protocol"`
	// Host is the host name or IP address of the endpoint.
	// This does not include the protocol or port.
	Host string `json:"host"`
	// Port is the port number of the endpoint.
	Port int `json:"port"`
}

Endpoint represents a target destination for funcie requests or bastions.

func MustNewEndpointFromAddress

func MustNewEndpointFromAddress(address string) Endpoint

MustNewEndpointFromAddress creates a new funcie Endpoint from parsing the given address.

func NewEndpoint

func NewEndpoint(scheme string, host string, port int) Endpoint

NewEndpoint creates a new Endpoint with the given scheme, host, and port.

func NewEndpointFromAddress

func NewEndpointFromAddress(address string) (Endpoint, error)

NewEndpointFromAddress creates a new funcie Endpoint from parsing the given address. Example: https://127.0.0.1:8080

func (Endpoint) String

func (e Endpoint) String() string

String returns a URL representation of the endpoint.

type Handler

type Handler func(ctx context.Context, message *Message) (*Response, error)

Handler is a function that handles a message from a tunnel.

type Message

type Message = MessageBase[json.RawMessage]

func MarshalMessagePayload

func MarshalMessagePayload[MessageType MessageBase[T], T any](message MessageType) (*Message, error)

MarshalMessagePayload marshals the given payload into a message with a serialized raw payload.

func NewMessage

func NewMessage(application string, kind MessageKind, payload []byte) *Message

NewMessage creates a new message with the given payload.

type MessageBase

type MessageBase[T any] struct {
	// ID is the unique identifier for this message.
	ID string `json:"id"`
	// Kind is the type of message that is being sent.
	Kind MessageKind `json:"kind"`
	// Application is the name of the application that this message is for.
	Application string `json:"application"`
	// Payload is the actual message payload.
	Payload T `json:"payload"`
	// Created is the time the message was created.
	Created time.Time `json:"created"`
}

MessageBase represents a message to be sent through a tunnel, typed to a specific payload kind. The generic message is aliased as Message, to allow for untyped use.

func NewMessageWithPayload

func NewMessageWithPayload[T any](application string, kind MessageKind, payload T) *MessageBase[T]

NewMessageWithPayload creates a new message with the given payload, which is serialized using funcie.MustSerialize.

func (*MessageBase[T]) String

func (m *MessageBase[T]) String() string

type MessageKind

type MessageKind string

MessageKind is the type of message that is being sent.

type Pinger

type Pinger interface {
	Ping(app Application) error
}

Pinger is an interface for pinging applications.

type ProxyError

type ProxyError struct {
	// Message is the error message.
	Message string `json:"message,omitempty"`
}

ProxyError is an error that can be sent through a tunnel.

func NewProxyError

func NewProxyError(message string) *ProxyError

NewProxyError creates a new ProxyError with the given message.

func NewProxyErrorFromError

func NewProxyErrorFromError(err error) *ProxyError

NewProxyErrorFromError creates a new ProxyError from the given error. If the error is nil, nil is returned.

func (*ProxyError) Error

func (e *ProxyError) Error() string

Error returns the error message.

func (*ProxyError) MarshalJSON

func (e *ProxyError) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*ProxyError) UnmarshalJSON

func (e *ProxyError) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Publisher

type Publisher interface {
	// Publish publishes a message to the tunnel, synchronously waiting for a response from the other side.
	// If no consumer is active, ErrNoConsumerActive is returned.
	Publish(ctx context.Context, message *Message) (*Response, error)
}

Publisher represents the publishing a synchronous tunnel that can be used to send messages to a consumer and wait for a response.

type Response

type Response = ResponseBase[json.RawMessage]

Response is a response to a message sent to a tunnel, with either a generic JSON payload or an error.

func MarshalResponsePayload

func MarshalResponsePayload[T any](response *ResponseBase[T]) (*Response, error)

MarshalResponsePayload marshals the payload of the given response into a JSON byte array.

func NewResponse

func NewResponse(id string, data []byte, error error) *Response

NewResponse creates a new response with the given data and the current time as the received time.

type ResponseBase

type ResponseBase[T any] struct {
	// ID is the unique identifier for this message.
	ID string `json:"id"`
	// Data is the actual message payload, or nil if an error occurred.
	// Exactly one of Data or Error are not nil.
	Data *T `json:"data,omitempty"`
	// Error is the error that occurred, or nil if no error occurred.
	// Exactly one of Data or Error are not nil.
	Error *ProxyError `json:"error,omitempty"`
	// Received is the time the response was received.
	Received time.Time `json:"received"`
}

ResponseBase represents a response to a message sent to a tunnel, with either a generic payload or an error.

func NewResponseWithPayload

func NewResponseWithPayload[T any](id string, payload *T, error error) *ResponseBase[T]

NewResponseWithPayload creates a new response with the given payload, which is serialized using funcie.MustSerialize, and the current time as the received time.

type Tunnel

type Tunnel interface {
	// Start starts the tunnel. This function never returns.
	// The handler is the handler that will be invoked when a request is received.
	// It is subject to the same restrictions as the handler for the serverless function provider (such as lambda.Start).
	Start()
}

func NewLambdaTunnel

func NewLambdaTunnel(applicationId string, handler interface{}, publisher Publisher, consumer Consumer) Tunnel