mikros

package module
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2024 License: MPL-2.0 Imports: 33 Imported by: 0

README

mikro_s

About

mikro_s is a Go framework for creating applications.

Introduction

This framework is an API built to ease and standardize the creation of applications that need to run for long periods, usually executing indefinitely, performing some specific operation. But it also supports standalone applications that execute its task and finishes right after.

Its main idea is to allow the user to create (or implement) an application, written in Go, of the following categories:

  • gRPC: an application with an API defined from a protobuf file.
  • HTTP: an HTTP server-type application, with its API defined from a protobuf file.
  • native: a general-purpose application, without a defined API, with the ability to execute any code for long periods.
  • script: also a general-purpose application, without a defined API, but that only needs to execute a single function and stop.
Service

Service, here, is considered an application that may or may not remain running indefinitely, performing some type of task or waiting for commands to activate it.

The framework consists of an SDK that facilitates the creation of these applications in a way that standardizes their code, so that they all perform tasks with the same behavior and are written in a very similar manner. In addition to providing flexibility, allowing these applications to also be customized when necessary.

Building a service using the framework's SDK must adhere to the following points:

  • Have a struct where mandatory methods according to its category must be implemented;
  • Initialize the SDK correctly;
  • Have a configuration file, called service.toml, containing information about itself and its functionalities.
Example of a service

The following example demonstrates how to create a service of a script type. The service structure implements an interface that makes it being supported by this type of service inside the framework.

package main

import (
    "context"

    "github.com/somatech1/mikros"
    "github.com/somatech1/mikros/components/options"
)

// service is a structure that will hold all required data and information
// of the service itself.
//
// It must have declared, at least, a member of type *mikros.Service. This
// gives it the ability of being used and supported by the framework internals.
type service struct {
    *mikros.Service
}

func (s *service) Run(ctx context.Context) error {
    s.Logger().Info(ctx, "service Run method executed")
    return nil
}

func (s *service) Cleanup(ctx context.Context) error {
    s.Logger().Info(ctx, "cleaning up things")
    return nil
}

func main() {
    // Creates a new service using the framework API.
    svc := mikros.NewService(&options.NewServiceOptions{
        Service: map[string]options.ServiceOptions{
            "script": &options.ScriptServiceOptions{},
        },
    })

    // Puts it to execute.
    svc.Start(&service{})
}

It must have a service.toml file with the following content:

name = "script-example"
types = ["script"]
version = "v1.0.0"
language = "go"
product = "Matrix"

When executed, it outputs the following (with a different time according the execution):

{"time":"2024-02-09T07:54:57.159265-03:00","level":"INFO","msg":"starting service","service.name":"script-example","service.type":"script","service.version":"v1.0.0","service.env":"local","service.product":"Matrix"}
{"time":"2024-02-09T07:54:57.159405-03:00","level":"INFO","msg":"starting dependent services","service.name":"script-example","service.type":"script","service.version":"v1.0.0","service.env":"local","service.product":"Matrix"}
{"time":"2024-02-09T07:54:57.159443-03:00","level":"INFO","msg":"service resources","service.name":"script-example","service.type":"script","service.version":"v1.0.0","service.env":"local","service.product":"Matrix","svc.http.auth":"false"}
{"time":"2024-02-09T07:54:57.159449-03:00","level":"INFO","msg":"service is running","service.name":"script-example","service.type":"script","service.version":"v1.0.0","service.env":"local","service.product":"Matrix","service.mode":"script"}
{"time":"2024-02-09T07:54:57.159458-03:00","level":"INFO","msg":"service Run method executed","service.name":"script-example","service.type":"script","service.version":"v1.0.0","service.env":"local","service.product":"Matrix"}
{"time":"2024-02-09T07:54:57.159464-03:00","level":"INFO","msg":"stopping service","service.name":"script-example","service.type":"script","service.version":"v1.0.0","service.env":"local","service.product":"Matrix"}
{"time":"2024-02-09T07:54:57.159467-03:00","level":"INFO","msg":"stopping dependent services","service.name":"script-example","service.type":"script","service.version":"v1.0.0","service.env":"local","service.product":"Matrix"}
{"time":"2024-02-09T07:54:57.159804-03:00","level":"INFO","msg":"cleaning up things","service.name":"script-example","service.type":"script","service.version":"v1.0.0","service.env":"local","service.product":"Matrix"}
{"time":"2024-02-09T07:54:57.159815-03:00","level":"INFO","msg":"service stopped","service.name":"script-example","service.type":"script","service.version":"v1.0.0","service.env":"local","service.product":"Matrix"}

Roadmap

  • Support for receiving custom 'service.toml' definition rules.
  • Support for HTTP services without being declared in a protobuf file.
  • Support for custom tags, key-value declared in the 'service.toml' file, to be added in each log line.
  • Remove unnecessary Logger APIs.

License

Mozilla Public License 2.0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetEnv added in v0.4.0 

func GetEnv(s string) string

GetEnv is a helper function that retrieves a value from an environment variable independently if is has the env notation or not.

func HasEnvNotation added in v0.4.0 

func HasEnvNotation(s string) bool

HasEnvNotation checks if a string has the mikros framework env notation indicating that it should be loaded from environment variables.

func ServiceName 

func ServiceName(name string) service.Name

ServiceName is the way to retrieve a service name from a string.

Types

type Env 

type Env struct {
	DeploymentEnv     definition.ServiceDeploy `env:"MIKROS_SERVICE_DEPLOY,default_value=local"`
	TrackerHeaderName string                   `env:"MIKROS_TRACKER_HEADER_NAME,default_value=X-Request-ID"`

	// CI/CD settings
	IsCICD bool `env:"MIKROS_CICD_TEST,default_value=false"`

	// Coupled clients
	CoupledNamespace string `env:"MIKROS_COUPLED_NAMESPACE"`
	CoupledPort      int32  `env:"MIKROS_COUPLED_PORT,default_value=7070"`

	// Default connection ports
	GrpcPort int32 `env:"MIKROS_GRPC_PORT,default_value=7070"`
	HttpPort int32 `env:"MIKROS_HTTP_PORT,default_value=8080"`
	// contains filtered or unexported fields
}

Env is the main framework environment structure. It holds only variables common for the whole project.

It is also the mechanism to hold all environment variables declared directly inside the 'service.toml' file.

func (*Env) DefinedEnv 

func (e *Env) DefinedEnv(name string) (string, bool)

func (*Env) ToMapEnv 

func (e *Env) ToMapEnv() *MapEnv

type MapEnv 

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

MapEnv is an Env subtype that can be passed to the plugin package options.

func (*MapEnv) CoupledNamespace 

func (m *MapEnv) CoupledNamespace() string

func (*MapEnv) CoupledPort 

func (m *MapEnv) CoupledPort() int32

func (*MapEnv) DeploymentEnv 

func (m *MapEnv) DeploymentEnv() definition.ServiceDeploy

func (*MapEnv) Get 

func (m *MapEnv) Get(key string) interface{}

func (*MapEnv) GrpcPort 

func (m *MapEnv) GrpcPort() int32

func (*MapEnv) HttpPort 

func (m *MapEnv) HttpPort() int32

func (*MapEnv) IsCICD 

func (m *MapEnv) IsCICD() bool

func (*MapEnv) TrackerHeaderName 

func (m *MapEnv) TrackerHeaderName() string

type Service 

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

Service is the object which represents a service application.

func NewService 

func NewService(opt *options.NewServiceOptions) *Service

NewService creates a new Service object for building and putting to run a new application.

We don't return an error here to force the application to end in case something wrong happens.

func (*Service) Abort 

func (s *Service) Abort(message string, err error)

Abort is a helper method to abort services in the right way, when external initialization is needed.

func (*Service) CustomDefinitions 

func (s *Service) CustomDefinitions() map[string]interface{}

CustomDefinitions gives the service access to the service custom settings that it may have put inside the 'service.toml' file.

Note that these settings correspond to everything under the service object inside the TOML file.

func (*Service) DeployEnvironment 

func (s *Service) DeployEnvironment() definition.ServiceDeploy

DeployEnvironment exposes the current service deploymentEnv environment.

func (*Service) Env 

func (s *Service) Env(name string) string

Env gives access to the framework environment variables public API.

func (*Service) Errors 

func (s *Service) Errors() errorsApi.ErrorFactory

Errors gives access to the errors API from inside a service context.

func (*Service) Feature 

func (s *Service) Feature(ctx context.Context, target interface{}) error

Feature is the service mechanism to have access to an external feature public API.

func (*Service) Logger 

func (s *Service) Logger() loggerApi.Logger

Logger gives access to the logger API from inside a service context.

func (*Service) ServiceName 

func (s *Service) ServiceName() string

ServiceName gives back the service name.

func (*Service) SetupTest 

func (s *Service) SetupTest(ctx context.Context, t *testing.Testing) *ServiceTesting

SetupTest is an api that should start the testing environment for a unit test.

func (*Service) Start 

func (s *Service) Start(srv interface{})

Start puts the service in execution mode and blocks execution. This function should be the last one called by the service.

We don't return an error here so that the service does not need to handle it inside its code. We abort in case of an error.

func (*Service) WithExternalFeatures 

func (s *Service) WithExternalFeatures(features *plugin.FeatureSet) *Service

WithExternalFeatures allows a service to add external features into it, so they can be used from it.

func (*Service) WithExternalServices 

func (s *Service) WithExternalServices(services *plugin.ServiceSet) *Service

WithExternalServices allows a service to add external service implementations into it.

type ServiceTesting 

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

ServiceTesting is an object created by a Service.SetupTest call.

It should be used when creating unit tests that need to use features, internal or external, and require some kind of setup/teardown mechanism.

func (*ServiceTesting) Do 

func (s *ServiceTesting) Do(ctx context.Context) error

Do is a function that executes tests from inside all registered features.

func (*ServiceTesting) Teardown 

func (s *ServiceTesting) Teardown(ctx context.Context)

Teardown releases every resource allocated by the SetupTest call.

Source Files

View all Source files

Directories

Path Synopsis
apis
errors
http
http_auth
http_cors
http_panic_recovery
lifecycle
logger
services/http
services/native
services/script
tracing
tracker
components
context
definition
env
errors
grpc
logger
options
plugin
service
testing
Package testing is a framework package to be used inside services unit tests providing an API to build specific services unit tests.
 Package testing is a framework package to be used inside services unit tests providing an API to build specific services unit tests.
internal
components/errors
components/lifecycle
components/logger
components/tags
components/tracker
components/validations
Package validations adds an internal framework API to validate structures without tag annotations.
 Package validations adds an internal framework API to validate structures without tag annotations.
features/http
services/grpc
services/http
services/native
services/script

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.