plugin

Documentation

Index

• type CanBeInitializedOptions
• type Entry
  • func (e *Entry) Error(in interface{}) error
  • func (e *Entry) IsEnabled() bool
  • func (e *Entry) Logger() loggerApi.Logger
  • func (e *Entry) Name() string
  • func (e *Entry) UpdateInfo(info UpdateInfoEntry)
  • func (e *Entry) WrapError(ctx context.Context, err error) error
• type Env
• type Feature
• type FeatureController
• type FeatureEntry
• type FeatureExternalAPI
• type FeatureInternalAPI
• type FeatureSet
  • func NewFeatureSet() *FeatureSet
  • func (s *FeatureSet) Append(features *FeatureSet)
  • func (s *FeatureSet) CleanupAll(ctx context.Context) error
  • func (s *FeatureSet) Count() int
  • func (s *FeatureSet) Feature(name string) (Feature, error)
  • func (s *FeatureSet) InitializeAll(ctx context.Context, options *InitializeOptions) error
  • func (s *FeatureSet) Iterator() *FeatureSetIterator
  • func (s *FeatureSet) Register(name string, feature Feature, dependencies ...string)
  • func (s *FeatureSet) StartAll(ctx context.Context, srv interface{}) error
• type FeatureSetIterator
  • func (i *FeatureSetIterator) Next() (Feature, bool)
  • func (i *FeatureSetIterator) Reset()
• type FeatureSettings
• type FeatureTester
• type InitializeOptions
• type Service
• type ServiceOptions
• type ServiceSet
  • func NewServiceSet() *ServiceSet
  • func (s *ServiceSet) Append(services *ServiceSet)
  • func (s *ServiceSet) Register(svc Service)
  • func (s *ServiceSet) Services() map[string]Service
• type ServiceSettings
• type UpdateInfoEntry

Types

type CanBeInitializedOptions

type CanBeInitializedOptions struct {
	DeploymentEnv definition.ServiceDeploy
	Definitions   *definition.Definitions
}

CanBeInitializedOptions gathers all information passed to the CanBeInitialized method of a Feature interface.

type Entry

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

Entry is a member that all framework feature must have declared inside of it (as a struct member). It implements the FeatureEntry interface for the feature if used.

Also, if a feature uses it, it already receives a logger.Logger interface for it for free and error methods to return a proper error for services.

func (*Entry) Error

func (e *Entry) Error(in interface{}) error

Error is a helper API to create an error value from a feature using a standard for all of them.

func (*Entry) IsEnabled

func (e *Entry) IsEnabled() bool

IsEnabled is a helper function that every public feature API should call at its beginning, to avoid executing it if it is disabled.

func (*Entry) Logger

func (e *Entry) Logger() loggerApi.Logger

Logger is a helper method that gives the feature access to the logger API.

func (*Entry) Name

func (e *Entry) Name() string

Name returns the internal feature name.

func (*Entry) UpdateInfo

func (e *Entry) UpdateInfo(info UpdateInfoEntry)

UpdateInfo is an internal method that allows a feature to have its information, such as its name, if it's enabled or not, internally.

func (*Entry) WrapError

func (e *Entry) WrapError(ctx context.Context, err error) error

WrapError is a helper API to create an error value from another error using the error standard of services APIs.

Usually, this method should be used when a public feature API returns an error.

type Env

type Env interface {
	// Get retrieves an environment variable value that was declared inside the
	// service.toml file.
	Get(key string) interface{}

	// DeploymentEnv gets the current service deployment environment.
	DeploymentEnv() definition.ServiceDeploy

	// TrackerHeaderName gives the current header name that contains the service
	// tracker ID (for HTTP services).
	TrackerHeaderName() string

	// IsCICD gets if the CI/CD is being running or not.
	IsCICD() bool

	// CoupledNamespace returns the namespace used by the services.
	CoupledNamespace() string

	// CoupledPort returns the port used to couple between services.
	CoupledPort() int32

	// GrpcPort returns the port number that gRPC services should use.
	GrpcPort() int32

	// HttpPort returns the port number that HTTP services should use.
	HttpPort() int32
}

Env is the plugin interface that allow plugins (features and services) to "access" the framework env.

type Feature

type Feature interface {
	// CanBeInitialized is the method executed to check if the feature is
	// allowed to be used by the current service or not. Here the feature
	// should check everything that is needs to return this information.
	CanBeInitialized(options *CanBeInitializedOptions) bool

	// Initialize is the method that "creates" the feature, where all its
	// required initialization must be made.
	Initialize(ctx context.Context, options *InitializeOptions) error

	// Fields should return informative fields to be logged at the beginning
	// of the execution.
	Fields() []loggerApi.Attribute

	// FeatureEntry is a set of methods that must provide information related
	// to the feature itself.
	FeatureEntry
}

Feature is a set of methods that all framework feature, internal or external, must implement to be supported.

type FeatureController

type FeatureController interface {
	// Start is a method where the plugin receives the service main object to
	// initialize custom tasks.
	Start(ctx context.Context, srv interface{}) error

	// Cleanup should free all resources allocated by the plugin or stop any
	// internal process.
	Cleanup(ctx context.Context) error
}

FeatureController is an optional behavior that a feature may have if it needs to execute tasks with the service main object.

type FeatureEntry

type FeatureEntry interface {
	// UpdateInfo is an internal method that allows a feature to have its
	// information, such as its name, if it's enabled or not, internally.
	UpdateInfo(info UpdateInfoEntry)

	// IsEnabled returns true or false if the feature is currently enabled or not.
	IsEnabled() bool

	// Name returns the feature name.
	Name() string
}

FeatureEntry is a set of methods that provide information related to the feature.

type FeatureExternalAPI

type FeatureExternalAPI interface {
	ServiceAPI() interface{}
}

FeatureExternalAPI is a behavior that every external feature must have so that their API can be used from services. This is specific for features that support test mocking.

type FeatureInternalAPI

type FeatureInternalAPI interface {
	FrameworkAPI() interface{}
}

FeatureInternalAPI is a behaviour that a feature can have to provide an API to be used inside the framework or its extensions.

type FeatureSet

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

FeatureSet gathers all features that a service can use during its execution.

func NewFeatureSet

func NewFeatureSet() *FeatureSet

NewFeatureSet creates a new FeatureSet.

func (*FeatureSet) Append

func (s *FeatureSet) Append(features *FeatureSet)

func (*FeatureSet) CleanupAll

func (s *FeatureSet) CleanupAll(ctx context.Context) error

func (*FeatureSet) Count

func (s *FeatureSet) Count() int

func (*FeatureSet) Feature

func (s *FeatureSet) Feature(name string) (Feature, error)

func (*FeatureSet) InitializeAll

func (s *FeatureSet) InitializeAll(ctx context.Context, options *InitializeOptions) error

InitializeAll initializes all previously registered feature (in the order they were registered).

func (*FeatureSet) Iterator

func (s *FeatureSet) Iterator() *FeatureSetIterator

func (*FeatureSet) Register

func (s *FeatureSet) Register(name string, feature Feature, dependencies ...string)

Register registers an internal feature that will be initialized, if allowed, to be used by a service. The features will be initialized in the order they are registered.

func (*FeatureSet) StartAll

func (s *FeatureSet) StartAll(ctx context.Context, srv interface{}) error

type FeatureSetIterator

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

func (*FeatureSetIterator) Next

func (i *FeatureSetIterator) Next() (Feature, bool)

func (*FeatureSetIterator) Reset

func (i *FeatureSetIterator) Reset()

type FeatureSettings

type FeatureSettings interface {
	// Definitions must return the feature definitions loaded from the
	// 'service.toml' file.
	//
	// To keep the framework standard, it's recommended that these custom
	// features settings reside inside a 'features' object inside the TOML
	// file. Like the example:
	//
	// [features.custom]
	//   custom_setting_a = 42
	//   custom_setting_b = "hello"
	//
	Definitions(path string) (definition.ExternalFeatureEntry, error)
}

FeatureSettings is an optional behavior that a feature may have to load custom settings from the service 'service.toml' file.

type FeatureTester

type FeatureTester interface {
	// Setup is responsible for changing internal behaviors when running a
	// specific unit test.
	Setup(ctx context.Context, t *testing.Testing)

	// Teardown is responsible for cleaning up all resources allocated when
	// Setup was called before. It's important to notice here that after this
	// call a new call to the Setup API must be made to run a new test.
	Teardown(ctx context.Context, t *testing.Testing)

	// DoTest is where the feature executes its specific tests previously
	// adjusted in the testing.Testing.Options.FeatureOptions.
	DoTest(ctx context.Context, t *testing.Testing, serviceName service.Name) error
}

FeatureTester is a behavior that a feature should implement to be mocked in a unit test.

type InitializeOptions

type InitializeOptions struct {
	Logger          loggerApi.Logger
	Errors          errorsApi.ErrorFactory
	Definitions     *definition.Definitions
	Tags            map[string]string
	ServiceContext  *mcontext.ServiceContext
	Dependencies    map[string]Feature
	RunTimeFeatures map[string]interface{}
	Env             Env
}

InitializeOptions gathers all information passed to the Initialize method of a Feature interface, allowing a feature to be properly initialized.

type Service

type Service interface {
	// Name must return the implementation name. It's recommended to use a
	// kebab-case here.
	Name() string

	// Info should return some service informative fields to be logged while
	// the application is starting.
	Info() []loggerApi.Attribute

	// Initialize must be the place to initialize everything that needs information
	// from the framework.
	Initialize(ctx context.Context, opt *ServiceOptions) error

	// Run must put the server in execution. It can block or not the call.
	Run(ctx context.Context, srv interface{}) error

	// Stop should stop the service with a graceful shutdown.
	Stop(ctx context.Context) error
}

Service is an internal package behavior that all supported service types must have.

type ServiceOptions

type ServiceOptions struct {
	Port           service.ServerPort
	Type           definition.ServiceType
	Name           service.Name
	Product        string
	Logger         loggerApi.Logger
	Errors         errorsApi.ErrorFactory
	ServiceContext *mcontext.ServiceContext
	Tags           map[string]string
	Service        options.ServiceOptions
	Definitions    *definition.Definitions
	Features       *FeatureSet
	ServiceHandler interface{}
	Env            Env
}

ServiceOptions gathers all available options to create a service object.

type ServiceSet

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

func NewServiceSet

func NewServiceSet() *ServiceSet

func (*ServiceSet) Append

func (s *ServiceSet) Append(services *ServiceSet)

func (*ServiceSet) Register

func (s *ServiceSet) Register(svc Service)

func (*ServiceSet) Services

func (s *ServiceSet) Services() map[string]Service

type ServiceSettings

type ServiceSettings interface {
	// Definitions must return the loaded service definitions from the
	// 'service.toml' file.
	//
	// To keep the framework standard, it's recommended that these custom
	// features settings use the service Name() as its main object inside
	// the TOML file. Like the example:
	//
	// [custom_service_name]
	//   custom_setting_a = 42
	//   custom_setting_b = "hello"
	//
	Definitions(path string) (definition.ExternalServiceEntry, error)
}

ServiceSettings is an optional behavior that a plugin may have to load custom settings from the service 'service.toml' file.

type UpdateInfoEntry

type UpdateInfoEntry struct {
	Enabled bool
	Name    string
	Logger  loggerApi.Logger
	Errors  errorsApi.ErrorFactory
}

UpdateInfoEntry is a structure used to update internal FeatureEntry types according its initialized members.