core

package
v0.321.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 14, 2024 License: Apache-2.0 Imports: 40 Imported by: 2

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (

	// Name is set at the build time.
	Name = ""

	// Version is set at the build time.
	Version = ""

	// BuildID is set at the build time.
	BuildID = ""

	// CommitSha is set at the build time.
	CommitSha = ""

	// BranchName is set at the build time.
	BranchName = ""

	// TagName is set at the build time.
	TagName = ""
)

Functions

func BuildDownstreamGRPCClient added in v0.56.0 

func BuildDownstreamGRPCClient(ctx context.Context, serviceName string, hooks *Hooks, cfg *config.CommonGRPCDownstreamData) (*grpc.ClientConn, error)

BuildDownstreamGRPCClient creates a grpc client connection to the target indicated by cfg.ServiceAddress. The dial options can be customised by cfg or by hooks, see ResolveGrpcDialOptions for details. The serviceName is the name of the target service. This function is intended to be called from generated code.

func BuildDownstreamHTTPClient 

func BuildDownstreamHTTPClient(ctx context.Context, serviceName string, hooks *Hooks, cfg *config.CommonDownstreamData) (client *http.Client, serviceURL string, err error)

func BuildDownstreamTemporalClient added in v0.283.0 

func BuildDownstreamTemporalClient(
	ctx context.Context,
	serviceName string,
	hooks *Hooks,
	cfg *config.CommonTemporalDownstreamData,
) (client.Client, error)

BuildDownstreamTemporalClient creates a temporal client connection to the target indicated by cfg.HostPort. The client options can be customised by cfg or by hooks.

func DefaultGrpcServerOptions added in v0.97.0 

func DefaultGrpcServerOptions(ctx context.Context, grpcPublicServerConfig *config.GRPCServerConfig) ([]grpc.ServerOption, error)

func GetAppConfigType added in v0.87.0 

func GetAppConfigType(createService interface{}) reflect.Type

GetAppConfigType extracts the app's config type from createService. Precondition: MustTypeCheckCreateService(createService, serviceInterface) succeeded.

func GetOptionFromClientIntf added in v0.292.0 

func GetOptionFromClientIntf(options []client.StartWorkflowOptions) client.StartWorkflowOptions

GetOptionFromClientIntf takes in the user provided options which is an array, check for length, and return an option.

func LoadCustomConfig added in v0.87.0 

func LoadCustomConfig(ctx context.Context, customConfig interface{}) (interface{}, error)

LoadCustomConfig populates the given zero customConfig value with configuration data.

func MustTypeCheckCreateService added in v0.87.0 

func MustTypeCheckCreateService(createService, serviceInterface interface{})

MustTypeCheckCreateService checks that the given createService has an acceptable type, and panics otherwise.

func NewZeroCustomConfig added in v0.87.0 

func NewZeroCustomConfig(downstreamConfigType, appConfigType reflect.Type) interface{}

NewZeroCustomConfig uses reflection to create a new type derived from DefaultConfig, but with new GenCode.Downstream and App fields holding the same types as downstreamConfig and appConfig. It returns a pointer to a zero value of that new type.

func Recoverer 

func Recoverer(next http.Handler) http.Handler

func ResolveGRPCAuthorizationRule added in v0.108.0 

func ResolveGRPCAuthorizationRule(ctx context.Context, h *Hooks, endpointName string, authRuleExpression string) (authrules.Rule, error)

func ResolveGrpcDialOptions added in v0.98.0 

func ResolveGrpcDialOptions(ctx context.Context, serviceName string, h *Hooks, grpcDownstreamConfig *config.CommonGRPCDownstreamData) ([]grpc.DialOption, error)

func ResolveGrpcServerOptions added in v0.97.0 

func ResolveGrpcServerOptions(ctx context.Context, h *Hooks, grpcPublicServerConfig *config.GRPCServerConfig) ([]grpc.ServerOption, error)

func ResolveRESTAuthorizationRule added in v0.109.0 

func ResolveRESTAuthorizationRule(ctx context.Context, h *Hooks, endpointName string, authRuleExpression string) (authrules.Rule, error)

func SelectBasePath 

func SelectBasePath(fromSpec, fromCfg string) string

SelectBasePath chooses between a basePath from the spec or config (config takes precedence).

func Serve added in v0.84.0 

func Serve(
	ctx context.Context,
	downstreamConfig, createService, serviceInterface interface{},
	newManagers func(ctx context.Context, serviceIntf interface{}, hooks *Hooks) (Manager, *GrpcServerManager, error),
) error

Serve is deprecated and will be removed once downstream applications cease depending upon it. Generated code will no longer call this function. This is a shim for compatibility with code generated by sysl-go versions v0.122.0 & earlier.

func TraceidLogInterceptor added in v0.97.0 

func TraceidLogInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error)

func WithConfigFile added in v0.146.0 

func WithConfigFile(ctx context.Context, yamlConfigData []byte) context.Context

WithConfigFile adds configuration data into the context. This will be used as the source of application configuration data, instead of the default behaviour of reading configuration from the config file path specified by command line arguments. Data must be in YAML format.

Types

type ErrDisplayHelp added in v0.154.0 

type ErrDisplayHelp int

func (ErrDisplayHelp) Error added in v0.154.0 

func (e ErrDisplayHelp) Error() string

type Future added in v0.289.0 

type Future[T any] struct {
	workflow.Future
}

func ExecuteActivity added in v0.289.0 

func ExecuteActivity[T any](ctx workflow.Context, tq, name string, args ...any) *Future[T]

func (*Future[T]) Get added in v0.289.0 

func (f *Future[T]) Get(ctx workflow.Context) (T, error)

type GrpcGenCallback added in v0.4.0 

type GrpcGenCallback interface {
	DownstreamTimeoutContext(ctx context.Context) (context.Context, context.CancelFunc)
}

GrpcGenCallback is currently a subset of RestGenCallback so is defined separately for convenience.

type GrpcManager deprecated 

type GrpcManager interface {
	Interceptors() []grpc.UnaryServerInterceptor
	EnabledGrpcHandlers() []handlerinitialiser.GrpcHandlerInitialiser
	GrpcAdminServerConfig() *config.CommonServerConfig
	GrpcPublicServerConfig() *config.GRPCServerConfig
}

Deprecated: prefer GrpcServerManager.

type GrpcServerManager added in v0.97.0 

type GrpcServerManager struct {
	GrpcServerOptions      []grpc.ServerOption
	EnabledGrpcHandlers    []handlerinitialiser.GrpcHandlerInitialiser
	GrpcPublicServerConfig *config.GRPCServerConfig
}

type HTTPManagerShim added in v0.91.0 

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

func NewHTTPManagerShim added in v0.91.0 

func NewHTTPManagerShim(libraryConfig *config.LibraryConfig, adminServerConfig *config.CommonHTTPServerConfig, publicServerConfig *config.UpstreamConfig, enabledHandlers []handlerinitialiser.HandlerInitialiser, addAdminHTTPMiddleware func(ctx context.Context, r chi.Router)) *HTTPManagerShim

func (*HTTPManagerShim) AddAdminHTTPMiddleware added in v0.169.0 

func (m *HTTPManagerShim) AddAdminHTTPMiddleware() func(ctx context.Context, r chi.Router)

func (*HTTPManagerShim) AdminServerConfig added in v0.91.0 

func (m *HTTPManagerShim) AdminServerConfig() *config.CommonHTTPServerConfig

func (*HTTPManagerShim) EnabledHandlers added in v0.91.0 

func (m *HTTPManagerShim) EnabledHandlers() []handlerinitialiser.HandlerInitialiser

func (*HTTPManagerShim) LibraryConfig added in v0.91.0 

func (m *HTTPManagerShim) LibraryConfig() *config.LibraryConfig

func (*HTTPManagerShim) PublicServerConfig added in v0.91.0 

func (m *HTTPManagerShim) PublicServerConfig() *config.UpstreamConfig

type HealthCheck added in v0.301.0 

type HealthCheck interface {
	Check(ctx context.Context, service string) (HealthCheckStatus, error)
}

type HealthCheckFunc added in v0.301.0 

type HealthCheckFunc func(context.Context, string) (HealthCheckStatus, error)

HealthCheckFunc is a type provided to make it easier to register health check endpoints by just supplying a Check function.

func (HealthCheckFunc) Check added in v0.301.0 

func (h HealthCheckFunc) Check(ctx context.Context, service string) (HealthCheckStatus, error)

type HealthCheckStatus added in v0.301.0 

type HealthCheckStatus int

HealthCheckStatus is an expected response for a health check function. 

const (
	UNKNOWN HealthCheckStatus = iota
	SERVING
	NOT_SERVING
	SERVICE_UNKNOWN
)

type Hooks added in v0.97.0 

type Hooks struct {

	// Logger returns the common.Logger instance to set use within Sysl-go.
	// By default, if this Logger hook is not set then an instance of the pkg logger is used.
	// This hook can also be used to define a custom logger.
	// For more information about logging see log/README.md within this project.
	// Note: The returned logger is guaranteed to have the log level from the external configuration
	// file (library: log: level) set against it.
	Logger func() log.Logger

	// MapError maps an error to an HTTPError in instances where custom error mapping is required.
	// Return nil to perform default error mapping; defined as:
	// 1. CustomError.HTTPError if the original error is a CustomError, otherwise
	// 2. common.MapError
	MapError func(ctx context.Context, err error) *common.HTTPError

	// WriteError can be used to write the error to the writer in whatever way you want.
	// If not supplied it will use httpError.WriteError as the default.
	WriteError func(ctx context.Context, w http.ResponseWriter, httpError *common.HTTPError)

	// AdditionalGrpcDialOptions can be used to append to the default grpc.DialOption configuration used by
	// an autogenerated service when it calls grpc.Dial when using a grpc.Client to connect to a gRPC server.
	// If given, AdditionalGrpcDialOptions will be appended to the list of default options created by
	// DefaultGrpcDialOptions(CommonGRPCDownstreamData).
	//
	// Use AdditionalGrpcDialOptions if you need both default and custom options. Be careful that you do
	// not specify any options that clash with the default options.
	//
	// If you need to completely override the default options, use OverrideGrpcDialOptions.
	// It is an error to set both AdditionalGrpcDialOptions and OverrideGrpcDialOptions.
	AdditionalGrpcDialOptions []grpc.DialOption

	// OverrideGrpcDialOptions can be used to override the default grpc.DialOption configuration used by an
	// an autogenerated service when it calls grpc.Dial when using a grpc.Client to connect to a gRPC server.
	//
	// The serviceName parameter will be filled with the name of the target service that we
	// are about to call grpc.Dial to connect to -- a function implementing this hook can use the
	// serviceName to customise different dial options for different targets.
	//
	// Prefer to use AdditionalGrpcDialOptions instead of OverrideGrpcDialOptions if you only need
	// to append to the default grpc.DialOption configuration instead of overriding it completely.
	//
	// It is an error to set both AdditionalGrpcDialOptions and OverrideGrpcDialOptions.
	OverrideGrpcDialOptions func(serviceName string, cfg *config.CommonGRPCDownstreamData) ([]grpc.DialOption, error)

	// AdditionalGrpcServerOptions can be used to append to the default grpc.ServerOption configuration used by
	// an autogenerated service when it creates a gRPC server. If given, AdditionalGrpcServerOptions will be
	// appended to the list of default options created by DefaultGrpcServerOptions(context.Context, CommonServerConfig).
	//
	// Use AdditionalGrpcServerOptions if you need both default and custom options. Be careful that you do
	// not specify any options that clash with the default options.
	//
	// If you need to completely override the default options, use OverrideGrpcServerOptions.
	// It is an error to set both AdditionalGrpcServerOptions and OverrideGrpcServerOptions.
	AdditionalGrpcServerOptions []grpc.ServerOption

	// OverrideGrpcServerOptions can be used to override the default grpc.ServerOption configuration used by an
	// autogenerated service when it creates a gRPC server.
	//
	// Prefer to use AdditionalGrpcServerOptions instead of OverrideGrpcServerOptions if you only need
	// to append to the default grpc.ServerOption configuration instead of overriding it completely.
	//
	// It is an error to set both AdditionalGrpcServerOptions and OverrideGrpcServerOptions.
	OverrideGrpcServerOptions func(ctx context.Context, grpcPublicServerConfig *config.GRPCServerConfig) ([]grpc.ServerOption, error)

	// ShouldSetGrpcGlobalLogger can be used to override the default value (true for normal runs and false for tests).
	//
	// The gRPC library has a function to set a global variable grpclog.SetLoggerV2, if we call it across multiple
	// tests it causes the race condition checker to error (it finds a legitimate race for multiple tests but not for
	// standard runs).
	ShouldSetGrpcGlobalLogger func() bool

	// OverrideMakeJWTClaimsBasedAuthorizationRule can be used to customise how authorization rule
	// expressions are evaluated and used to decide if JWT claims are authorised. By default, if this
	// hook is nil, then authrules.MakeDefaultJWTClaimsBasedAuthorizationRule is used.
	OverrideMakeJWTClaimsBasedAuthorizationRule func(authorizationRuleExpression string) (authrules.JWTClaimsBasedAuthorizationRule, error)

	// AddHTTPMiddleware can be used to install additional HTTP middleware into the chi.Router
	// used to serve all (non-admin) HTTP endpoints. By default, sysl-go installs a number of
	// HTTP middleware -- refer to prepareMiddleware inside sysl-go/core. This hook can only
	// be used to add middleware, not override any of the default middleware.
	AddHTTPMiddleware func(ctx context.Context, r chi.Router)

	// AddAdminHTTPMiddleware can be used to install additional HTTP middleware into the chi.Router
	// used to serve the admin HTTP endpoints. See AddHTTPMiddleware for further details.
	AddAdminHTTPMiddleware func(ctx context.Context, r chi.Router)

	// DownstreamRoundTripper can be used to install additional HTTP RoundTrippers to the downstream clients
	DownstreamRoundTripper func(serviceName string, serviceURL string, original http.RoundTripper) http.RoundTripper

	// ValidateConfig can be used to validate (or override) values in the config.
	ValidateConfig func(ctx context.Context, cfg *config.DefaultConfig) error

	// HTTPClientBuilder can be used to add a function which will be used to create the downstream HTTP clients
	// instead of the normal generator. This can be used to create custom test HTTP clients.
	HTTPClientBuilder func(serviceName string) (client *http.Client, serviceURL string, err error)

	// StoppableServerBuilder can be used to add a function which will be used to create the public listener
	// instead of the normal httpServer. This can be used to create custom test HTTP listeners.
	StoppableServerBuilder func(ctx context.Context, rootRouter http.Handler, tlsConfig *tls.Config, httpConfig config.CommonHTTPServerConfig, name string) StoppableServer

	// StoppableGrpcServerBuilder can be used to add a function which will be used to create the public gRPC listener
	// instead of the normal net.Listen. This can be used to create custom test gRPC listeners.
	StoppableGrpcServerBuilder func(ctx context.Context, server *grpc.Server, commonConfig config.GRPCServerConfig, name string) StoppableServer

	// ExperimentalValidateTemporalClientOptions can be used to validate (or override) client options to connect to a
	// temporal instance with.
	ExperimentalValidateTemporalClientOptions func(context.Context, *client.Options) error

	// ExperimentalValidateTemporalWorkerOptions can be used to validate (or override) worker options to connect to a
	// temporal instance with.
	ExperimentalValidateTemporalWorkerOptions func(context.Context, *worker.Options) error

	// ExperimentalTemporalClientBuilder can be used to build a custom temporal client.
	ExperimentalTemporalClientBuilder func(context.Context, string, *client.Options) (client.Client, error)

	// ExperimentalTemporalWorkerBuilder can be used to build a custom temporal worker.
	ExperimentalTemporalWorkerBuilder func(client client.Client, taskQueue string, options worker.Options) worker.Worker

	// HealthCheck can be used to provide custom health check endpoints for your service.
	// Currently only gRPC service is supported by implementing grpc.health.v1 when this field is set.
	HealthCheck HealthCheck
}

Hooks can be used to customise the behaviour of an autogenerated sysl-go service.

type Manager 

type Manager interface {
	EnabledHandlers() []handlerinitialiser.HandlerInitialiser
	LibraryConfig() *config.LibraryConfig
	AdminServerConfig() *config.CommonHTTPServerConfig
	PublicServerConfig() *config.UpstreamConfig

	// AddAdminHTTPMiddleware can return nil if you do not have any additional middleware for the admin endpoint
	AddAdminHTTPMiddleware() func(ctx context.Context, r chi.Router)
}

type MultiError added in v0.123.0 

type MultiError struct {
	Msg    string
	Errors []error
}

FIXME replace MultiError with some existing type that does this job better.

func (MultiError) Error added in v0.123.0 

func (e MultiError) Error() string

type RestGenCallback added in v0.4.0 

type RestGenCallback interface {
	// AddMiddleware allows hand-crafted code to add middleware to the router
	AddMiddleware(ctx context.Context, r chi.Router)
	// BasePath allows hand-crafted code to set the base path for the Router
	BasePath() string
	// Config returns a structure representing the server config
	// This is returned from the status endpoint
	Config() interface{}
	// MapError maps an error to an HTTPError in instances where custom error mapping is required. Return nil to perform default error mapping; defined as:
	// 1. CustomError.HTTPError if the original error is a CustomError, otherwise
	// 2. common.MapError
	MapError(ctx context.Context, err error) *common.HTTPError
	// WriteError can be used to write the error to the writer in whatever way you want
	// Call httpError.WriteError(ctx, w) to get the default behaviour
	WriteError(ctx context.Context, w http.ResponseWriter, httpError *common.HTTPError)
	// DownstreamTimeoutContext add the desired timeout duration to the context for downstreams
	// A separate service timeout (usually greater than the downstream) should also be in
	// place to automatically respond to callers
	DownstreamTimeoutContext(ctx context.Context) (context.Context, context.CancelFunc)
}

RestGenCallback is used by `sysl-go` to call hand-crafted code.

type Run added in v0.283.0 

type Run[T any] struct {
	client.WorkflowRun
}

func ExecuteWorkflow added in v0.283.0 

func ExecuteWorkflow[T any](ctx context.Context, option client.StartWorkflowOptions, c client.Client, tq, name string, args ...any) (*Run[T], error)

func (*Run[T]) Get added in v0.283.0 

func (r *Run[T]) Get(ctx context.Context) (T, error)

func (*Run[T]) GetWithOptions added in v0.283.0 

func (r *Run[T]) GetWithOptions(ctx context.Context, options client.WorkflowRunGetOptions) (T, error)

type ServiceDefinition added in v0.294.0 

type ServiceDefinition[AppConfig, ServiceIntf any] func(context.Context, AppConfig) (ServiceIntf, *Hooks, error)

type StoppableServer added in v0.123.0 

type StoppableServer interface {
	// Start() directs the server to attempt to start serving. This call will block
	// until a failure occurs, or the server is stopped. If the server is not stopped
	// and no failure occurs, this call may block indefinitely.
	// On a successful stop() or gracefulstop(), no error is returned.
	Start() error

	// Stop() directs the server to immediately and un-gracefully stop, which may
	// interrupt any in-flight requests/calls being processed.
	Stop() error

	// GracefulStop() directs the server to stop accepting new requests/calls and
	// wait for any in-flight requests/calls to complete. Implementations of
	// GracefulStop() should ensure they bring the server to a stop after some
	// bounded period of time, even if this involves ungracefully dropping some
	// laggard requests/calls.
	GracefulStop() error

	GetName() string
}

StoppableServer offers control over the lifecycle of a server that can be started at most once and then stopped.

func NewMultiStoppableServer added in v0.202.0 

func NewMultiStoppableServer(ctx context.Context, servers []StoppableServer) StoppableServer

func NewServer added in v0.123.0 

func NewServer(
	ctx context.Context,
	downstreamConfig, createService, serviceInterface interface{},
	newManagers func(ctx context.Context, serviceIntf interface{}, hooks *Hooks) (Manager, *GrpcServerManager, error),
) (StoppableServer, error)

NewServer returns an auto-generated service.

func NewTemporalWorker added in v0.289.0 

func NewTemporalWorker[
	TemporalServiceHandler, DownstreamConfig, AppConfig, ServiceIntf, Clients any,
	Spec TemporalServiceSpec[TemporalServiceHandler],
](
	ctx context.Context,
	taskQueueName string,
	downstreamConfig DownstreamConfig,
	createService ServiceDefinition[AppConfig, ServiceIntf],
	buildDownstreamsClients func(context.Context, *Hooks) (Clients, error),
	buildServiceHandler func(client.Client, worker.Worker, ServiceIntf, Clients) Spec,
) (StoppableServer, error)

NewTemporalWorker creates a Temporal Worker that implements StoppableServer. This is meant to be called by a generated temporal worker.

`ctx` is a context created by user. `taskQueueName` is a generated task queue name for temporal worker. `downstreamConfig` is a generated configuration for downstream. `createService` is user-provided function that creates a struct of handlers. `buildDownstreamsClients` is a generated function that creates clients for each downstream. `buildServiceHandler` is a generated function that creates temporal service handler. temporal service handler itself is a generated struct that wraps downstreams and user handlers.

type TLSLogFilter 

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

func (*TLSLogFilter) Write 

func (t *TLSLogFilter) Write(p []byte) (n int, err error)

type TemporalServer added in v0.289.0 

type TemporalServer[Spec any] struct {
	Spec TemporalServiceSpec[Spec]
}

func (*TemporalServer[Spec]) GetName added in v0.289.0 

func (t *TemporalServer[Spec]) GetName() string

func (*TemporalServer[Spec]) GetSpec added in v0.294.0 

func (t *TemporalServer[Spec]) GetSpec() TemporalServiceSpec[Spec]

func (*TemporalServer[Spec]) GracefulStop added in v0.289.0 

func (t *TemporalServer[Spec]) GracefulStop() error

func (*TemporalServer[Spec]) Start added in v0.289.0 

func (t *TemporalServer[Spec]) Start() error

func (*TemporalServer[Spec]) Stop added in v0.289.0 

func (t *TemporalServer[Spec]) Stop() error

type TemporalServiceSpec added in v0.289.0 

type TemporalServiceSpec[T any] interface {
	worker.Worker
	client.Client

	Register()
	GetWorker() worker.Worker
	GetClient() client.Client
	GetService() T
	Close()
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.