mikros

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

• func GetEnv(s string) string
• func HasEnvNotation(s string) bool
• func ServiceName(name string) service.Name
• type Env
  • func (e *Env) DefinedEnv(name string) (string, bool)
  • func (e *Env) ToMapEnv() *MapEnv
• type MapEnv
  • func (m *MapEnv) CoupledNamespace() string
  • func (m *MapEnv) CoupledPort() int32
  • func (m *MapEnv) DeploymentEnv() definition.ServiceDeploy
  • func (m *MapEnv) Get(key string) interface{}
  • func (m *MapEnv) GrpcPort() int32
  • func (m *MapEnv) HttpPort() int32
  • func (m *MapEnv) IsCICD() bool
  • func (m *MapEnv) TrackerHeaderName() string
• type Service
  • func NewService(opt *options.NewServiceOptions) *Service
  • func (s *Service) Abort(message string, err error)
  • func (s *Service) CustomDefinitions() map[string]interface{}
  • func (s *Service) DeployEnvironment() definition.ServiceDeploy
  • func (s *Service) Env(name string) string
  • func (s *Service) Errors() errorsApi.ErrorFactory
  • func (s *Service) Feature(ctx context.Context, target interface{}) error
  • func (s *Service) Logger() loggerApi.Logger
  • func (s *Service) ServiceName() string
  • func (s *Service) SetupTest(ctx context.Context, t *testing.Testing) *ServiceTesting
  • func (s *Service) Start(srv interface{})
  • func (s *Service) WithExternalFeatures(features *plugin.FeatureSet) *Service
  • func (s *Service) WithExternalServices(services *plugin.ServiceSet) *Service
• type ServiceTesting
  • func (s *ServiceTesting) Do(ctx context.Context) error
  • func (s *ServiceTesting) Teardown(ctx context.Context)

Functions

func GetEnv

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

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.