services

type ContentFileNameGetter ¶

type ContentFileNameGetter interface {
	// ContentFileName returns the name of the file that should be used when downloading this stream.
	ContentFileName() string
}

ContentFileNameGetter is used to supply an optional Content-Disposition header, allowing you to customize the name of the file presented in download modals of browsers/clients.

type ContentFileNameSetter ¶

type ContentFileNameSetter interface {
	// SetContentFileName applies the name of the file that should be used when downloading this stream.
	SetContentFileName(string)
}

ContentFileNameSetter is used to supply an optional Content-Disposition header, allowing you to customize the name of the file presented in download modals of browsers/clients.

type ContentGetter ¶

type ContentGetter interface {
	// Content returns the stream of exact bytes to send back to the caller.
	Content() io.ReadCloser
}

ContentGetter provides a way for your service response to indicate that you want to return a raw stream of bytes rather than relying on our auto-encoding.

type ContentLengthGetter ¶

type ContentLengthGetter interface {
	// ContentLength returns the total number of bytes you can/should read from the Content stream.
	ContentLength() int
}

ContentLengthGetter is used by raw response streams to indicate exactly how many bytes are in the response's Content stream.

type ContentLengthSetter ¶

type ContentLengthSetter interface {
	// SetContentLength applies the total number of bytes you can/should read from the Content stream.
	SetContentLength(int)
}

ContentLengthSetter recaptures the custom content length header from raw responses when using the code-generate Go client for your services.

type ContentRangeGetter ¶

type ContentRangeGetter interface {
	// ContentRange returns the individual values used to build a custom Content-Range header
	// when responding with a raw content stream. For more information on how these values are
	// used, please see: https://www.geeksforgeeks.org/http-headers-content-range/
	ContentRange() (start int, end int, size int)
}

ContentRangeGetter is used by raw response streams to indicate that this is resumable using the standard Range header.

type ContentRangeSetter ¶

type ContentRangeSetter interface {
	// SetContentRange accepts the 3 standard components of the Content-Range header.
	SetContentRange(start int, end int, size int)
}

ContentRangeSetter recaptures the custom content range header from raw responses when using the code-generated Go client for your services.

type ContentSetter ¶

type ContentSetter interface {
	// SetContent applies the stream of bytes that the response object should use when reading.
	SetContent(io.ReadCloser)
}

ContentSetter allows raw stream responses to be properly reconstituted when using the code-generated Go client for your service.

type ContentTypeGetter ¶

type ContentTypeGetter interface {
	// ContentType returns the MIME encoding type of the raw content stream.
	ContentType() string
}

ContentTypeGetter is used by raw response streams to indicate what type of data is in the stream.

type ContentTypeSetter ¶

type ContentTypeSetter interface {
	// SetContentType sets the MIME encoding type of the raw content stream.
	SetContentType(string)
}

ContentTypeSetter recaptures the custom content type header from raw responses when using the code-generated Go client for your service.

type Endpoint ¶

type Endpoint struct {
	// ServiceName is the name of the service that this operation is part of.
	ServiceName string
	// Name is the name of the function/operation that this endpoint describes.
	Name string
	// Handler is the actual function that will trigger the work on then underlying
	// service to accomplish the work that this endpoint is intended to.
	Handler HandlerFunc
	// NewInput returns a pointer to the struct that we pass into the handler function
	// for this input (e.g. "*LoginRequest"). It is the request struct pointer.
	NewInput func() StructPointer
	// Roles helps support role-based security by defining role patterns to indicate which
	// users are allowed to access this endpoint.  For example:
	//
	//    endpoint.Roles = []string{
	//        "admin.write",
	//        "group.{Group.ID}.write",
	//    }
	//
	// Notices that the roles should be allowed to have path variables that we can fill in
	// at runtime with the incoming binding data.
	Roles []string
	// Routes defines the actual ingress routes that allow this service operation to
	// be invoked by various gateways. For instance, they tell you that you can invoke
	// the API call "GET /user/{ID}" to invoke it or that it should trigger when the
	// event "ON UserService.UserCreated" fires.
	Routes []EndpointRoute
}

Endpoint describes an operation on an underlying service that we expose through one of potentially multiple gateways. The Routes on this Endpoint indicate all of the ingress mechanisms available to invoke this operation.

func (end Endpoint) QualifiedName() string

type EndpointRoute ¶

type EndpointRoute struct {
	// GatewayType indicates the type of gateway that should service this route. For instance
	// if the type is "HTTP" then the API gateway should take care of it. If the type
	// is "EVENT" then we should let our pub-sub event source take care of it.
	GatewayType GatewayType
	// Method describes some sort of action/verb that describes this route. For API endpoints
	// it is the HTTP method (e.g. GET, PUT, POST, etc). For events it is "ON", and so forth.
	Method string
	// Path describes the actual unique routing path that the gateway should use to ensure
	// that requests get to this endpoint. For API endpoints, it's the request path
	// like "/user/{ID}" and for event endpoints, it's the subscription key like "FooService.Save".
	Path string
	// PathParams contains the names of the path variables/parameters you expect in the path of
	// this endpoint. For instance, the path "/user/{UserID}/transaction/{TransactionID}" would set
	// this slice to []string{"UserID", "TransactionID"}. This allows you to quickly bind only the
	// values you expect in the pattern.
	PathParams []string
	// Status is mainly used by API gateway routes to determine what HTTP status code we should
	// return to the caller when this endpoint succeeds. By default, this is 200.
	Status int
}

EndpointRoute defines an actual ingress route that allows a service operation to be invoked by various gateways. For instance, one route will tell you that you can invoke the API call "GET /user/{ID}" to invoke the method or that it should run when the event "ON UserService.UserCreated" fires.

type Gateway ¶

type Gateway interface {
	// Type returns the identifier used to distinguish this gateway from others registered
	// for the same service.
	Type() GatewayType
	// Register adds an ingress handler for the given operation/endpoint to this gateway.
	Register(endpoint Endpoint, route EndpointRoute)
	// Listen causes the gateway to start accepting requests to invoke methods on the
	// underlying service. Implementations should attempt to follow these rules:
	//
	//   * Block on the current Goroutine. This should unblock on an abnormal interruption
	//     to the gateway's ability to continue processing or if Shutdown() has been
	//     called elsewhere.
	//   * The error should be 'nil' if nothing has gone wrong. This is different from the
	//     behavior of http.ListenAndServe() which returns a http.ErrServerClosed error
	//     even when things shut down as expected. Gateway instances should keep their
	//     whore mouths shut and only report an error when there's actually something
	//     to be concerned about.
	Listen() error
	// Shutdown should attempt to gracefully wind down processing of requests. Where
	// possible, you should use the context to determine if/when you should give up
	// on dealing with existing work. Implementations should try to follow these rules:
	//
	//   * Immediately stop accepting incoming requests.
	//   * Allow in-process requests to finish cleanly.
	//   * Abide any cancellation of the context and give up on existing requests.
	Shutdown(ctx context.Context) error
}

Gateway describes a way to execute operations on some underlying service. By default, service methods are closed off to all external processes, but gateways provide a protocol such as HTTP/RPC or PubSub to trigger them. How that actually happens is completely up to the Gateway implementation - the interface merely provides signals to start/stop the mechanism that accepts/processes function calls.

type GatewayMiddleware ¶

type GatewayMiddleware interface {
	Gateway
	// Middleware are the functions that a Server should add to EVERY endpoint it registers.
	Middleware() MiddlewareFuncs
}

GatewayMiddleware allows gateway implementations to add special middleware to the standard execution pipeline for an endpoint. Your gateway would implement this when it has special functionality you want included in the execution of every endpoint regardless of which gateway is actually servicing it.

The canonical example for this is the event gateway. When a service method gets invoked, we want to publish a "Service.Method" event afterwards no matter what so that the rest of your system can be notified about the event. We don't care if it was an HTTP request that triggered the invocation or some other event handler. We just know that we want to publish an event no matter what. The event middleware can return a handler(s) that injects that behavior by hiding it behind a generic middleware function.

type GatewayType ¶

type GatewayType string

GatewayType is a tagging value that gateways can use to classify themselves.

func (t GatewayType) String() string

type HandlerFunc ¶

type HandlerFunc func(ctx context.Context, req any) (any, error)

HandlerFunc is the general purpose signature for any endpoint handler.

type MiddlewareFunc ¶

type MiddlewareFunc func(ctx context.Context, req any, next HandlerFunc) (any, error)

MiddlewareFunc is a function that can be used to decorate a service method/endpoint's handler.

type MiddlewareFuncs ¶

type MiddlewareFuncs []MiddlewareFunc

MiddlewareFuncs is an ordered pipeline of operations that must occur before invoking a service method/endpoint's handler.

func (funcs MiddlewareFuncs) Append(mw ...MiddlewareFunc) MiddlewareFuncs

func (funcs MiddlewareFuncs) Then(handler HandlerFunc) HandlerFunc

type OnPanicFunc ¶

type OnPanicFunc func(err error, stack []byte)

OnPanicFunc is the signature for custom callbacks to invoke when a panic occurs in your service code.

type Redirector ¶

type Redirector interface {
	// Redirect returns the URI of an alternate resource that will provide the final data
	// we want this endpoint to return.
	Redirect() string
}

Redirector provides a way to tell gateways that the response value doesn't contain the raw byte stream we want to deliver. Instead, you should redirect to that URI to fetch the response data.

This indicates the redirect is temporary, and you should probably continue to use the same endpoint address in the future. You'd probably use this more in cases such as redirecting to a file on S3; something that will be different each time.

GATEWAY COMPATABILITY: This currently only works with the API gateway. When delivering/receiving responses through other gateways such as "Events", your response will be auto-encoded just like it was a normal struct/value. As a result, your response should continue to maintain exported fields that you would like to transport in those cases.

type RedirectorPermanent ¶

type RedirectorPermanent interface {
	// RedirectPermanent returns the URI of an alternate resource that will provide the final data
	// we want this endpoint to return.
	RedirectPermanent() string
}

RedirectorPermanent provides a way to tell gateways that the response value doesn't contain the raw byte stream we want to deliver. Instead, you should redirect to that URI to fetch the response data.

This indicates that the redirect is permanent, and you should probably start using the redirected URI moving forward. You'd probably use this more in a situation where you are deprecating one API endpoint in favor of another. The old endpoint could redirect to the new endpoint to maintain backwards compatability, but you really should start using the new one.

GATEWAY COMPATABILITY: This currently only works with the API gateway. When delivering/receiving responses through other gateways such as "Events", your response will be auto-encoded just like it was a normal struct/value. As a result, your response should continue to maintain exported fields that you would like to transport in those cases.

type Server ¶

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

Server is the primordial component that wrangles all of your services and gateways to get them talking to each other. You should not create one of these yourself. Instead, you should use the NewServer() constructor to do that for you.

func NewServer(options ...ServerOption) *Server

calcHandler := calc.CalculatorServiceHandler{}
calcServer := gen.NewCalculatorService(calcHandler)

server := services.NewServer(
	services.Listen(apis.NewGateway()),
	services.Listen(events.NewGateway()),
	services.Register(calcServer),
)

func (server *Server) Invoke(ctx context.Context, serviceName string, methodName string, req any) (any, error)

func (server *Server) Run() error

func (server *Server) Shutdown(ctx context.Context) error

func (server *Server) ShutdownOnInterrupt(gracefulTimeout time.Duration)

// Ignore the bad (non-existent) error handling, but here's how your server
// setup/teardown code looks using ShutdownOnInterrupt. The server will start
// up and run until the process gets a SIGINT/SIGTERM signal. At that point, it
// will give all in-process requests in all gateways 10 seconds to finish.
void main() {
	server := services.NewServer(...)
	go server.ShutdownOnInterrupt(10*time.Second)
	server.Run()
}

type ServerOption ¶

type ServerOption func(*Server)

ServerOption defines a setting that you can change on a services.Server while setting up your application in main().

func Listen(gw Gateway) ServerOption

func OnPanic(handler OnPanicFunc) ServerOption

func Register(services ...*Service) ServerOption

type Service ¶

type Service struct {
	// Name is the name of the service interface that we're building a server for.
	Name string
	// Version is an optional version identifier for this service.
	Version string
	// Handler is a reference to the actual service handler struct you provided during
	// setup of the gateway runtime in main.
	Handler any
	// Endpoints contains registration/execution information for every method/operation
	// that the service exposes.
	Endpoints []Endpoint
}

Service encapsulates your hand-implemented service handler and includes all of the endpoint registration information required to power our runtime gateways.

func (svc Service) Endpoint(name string) (Endpoint, bool)

type StreamRequest ¶

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

StreamRequest implements all of the ContentXxx and SetContentXxx methods that we support and look at when we look at streaming/upload style requests.

type FileUploadRequest struct {
	services.StreamRequest
}

func (res *ImageDownloadResponse) Init(file os.File, info fs.FileInfo) {
	res.SetContent(file)
	res.SetContentType("image/png")
	res.SetContentLength(info.Size())
}

type StreamResponse ¶

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

StreamResponse implements all of the ContentXxx and SetContentXxx methods that we support. You can embed one of these structs in your response struct to automatically gain the ability to respond with raw data streams rather than auto-encoding.

type ImageDownloadResponse struct {
	services.StreamResponse
}

func (res *ImageDownloadResponse) Init(file os.File, info fs.FileInfo) {
	res.SetContent(file)
	res.SetContentType("image/png")
	res.SetContentLength(info.Size())
}

func (res *StreamResponse) Content() io.ReadCloser

func (res *StreamResponse) ContentFileName() string

func (res *StreamResponse) ContentLength() int

func (res *StreamResponse) ContentRange() (start int, end int, size int)

func (res *StreamResponse) ContentType() string

func (res *StreamResponse) SetContent(content io.ReadCloser)

func (res *StreamResponse) SetContentFileName(contentFileName string)

func (res *StreamResponse) SetContentLength(contentLength int)

func (res *StreamResponse) SetContentRange(start int, end int, size int)

func (res *StreamResponse) SetContentType(contentType string)

type StructPointer ¶

type StructPointer any

StructPointer is a tagging type used to indicate either a pointer to the "request" struct to service methods or a pointer to the "response" struct of the method.