runtime

README

Runtime Package

Introduction

The current go package defines the general configuration of the service runtime, as well as the loading of the runtime configuration.

The Runtime controls the resources required when a project is started, including configuration files, logs, monitoring, caches, and databases.

Before You Start

Before you start using the Runtime package, ensure that you have the following prerequisites: In order to prevent import conflicts caused by packages with the same name as kratos, packages with the same name in this database will import the export content from kratos. All type definitions will be prefixed with the K fixed prefix. Note: Only type declarations are prefixed, not functions.

Available Packages

• bootstrap: The bootstrap package contains Configuration file reading and writing, initialization variable declaration, etc
• config: The files in this directory define the basic configuration of the service runtime, as well as the loading of the run configuration.
• context: The context directory defines the context interface and the context implementation.
• data: The data directory defines the data interface, caching, database, and other storage implementation.
• gen: The protobuf directory contains the definition of the protobuf protocol.
• proto: For compatibility with other languages, the interface is defined using proto files and implemented using gRPC. All proto definition files used by the Runtime are placed in 'proto' directory.
• mail: The mail directory defines the email interface and the email implementation.
• middleware: The middleware directory defines the middleware interface and the middleware
• registry: This directory defines an alias for 'kratos/v2/registry', primarily for backward compatibility and for placing import error paths.
• service: The service directory contains the definition of the service interface, which is used to define the interface of the service and the implementation of the service.

Getting Started

To incorporate the Toolkit into your project, follow these steps:

1. Add the dependency: Add the Toolkit as a dependency in your go.mod file, specifying the latest version:

go get github.com/origadmin/toolkit/runtime@vX.Y.Z

Replace vX.Y.Z with the desired version or latest to fetch the most recent release.

1. Import required packages: In your Go source files, import the necessary packages from the Toolkit:

import (
"github.com/origadmin/toolkit/runtime"
"github.com/origadmin/toolkit/runtime/config"
"github.com/origadmin/toolkit/runtime/registry"
)

// NewDiscovery creates a new discovery.
func NewDiscovery(registryConfig *config.RegistryConfig) registry.Discovery {
if registryConfig == nil {
panic("no registry config")
}
discovery, err := runtime.NewDiscovery(registryConfig)
if err != nil {
panic(err)
}
return discovery
}

// NewRegistrar creates a new registrar.
func NewRegistrar(registryConfig *config.RegistryConfig) registry.Registrar {
if registryConfig == nil {
panic("no registry config")
}
registrar, err := runtime.NewRegistrar(registryConfig)
if err != nil {
panic(err)
}
return registrar
}

Contributing

We welcome contributions from the community to improve and expand the Toolkit. To contribute, please follow these guidelines:

1. Familiarize yourself with the project: Read the CONTRIBUTING file for details on the contribution process, code style, and Pull Request requirements.
2. Submit an issue or proposal: If you encounter any bugs, have feature suggestions, or want to discuss potential changes, create an issue in the GitHub repository.
3. Create a Pull Request: After implementing your changes, submit a Pull Request following the guidelines outlined in CONTRIBUTING.

Contributors

Code of Conduct

All contributors and participants are expected to abide by the Contributor Covenant, version 2.1. This document outlines the expected behavior when interacting with the Toolkit community.

License

The Toolkit is distributed under the terms of the MIT. This permissive license allows for free use, modification, and distribution of the toolkit in both commercial and non-commercial contexts.

Documentation

Overview

Package runtime implements the functions, types, and interfaces for the module.

Package runtime implements the functions, types, and interfaces for the module.

Package runtime implements the functions, types, and interfaces for the module.

Package runtime implements the functions, types, and interfaces for the module.

Package runtime implements the functions, types, and interfaces for the module.

Package runtime implements the functions, types, and interfaces for the module.

Package runtime implements the functions, types, and interfaces for the module.

Package runtime provides functions for loading configurations and registering services.

Index

• Constants
• Variables
• func LoadConfig(path string, v any, ss ...config.Option) error
• func LoadConfigFromBootstrap(bs *bootstrap.Bootstrap, v any, ss ...config.Option) error
• func NewConfig(cfg *configv1.SourceConfig, ss ...config.Option) (config.KConfig, error)
• func NewDiscovery(cfg *configv1.Discovery, ss ...registry.Option) (registry.KDiscovery, error)
• func NewGRPCServiceClient(ctx context.Context, cfg *configv1.Service, ss ...service.GRPCOption) (*service.GRPCClient, error)
• func NewGRPCServiceServer(cfg *configv1.Service, ss ...service.GRPCOption) (*service.GRPCServer, error)
• func NewHTTPServiceClient(ctx context.Context, cfg *configv1.Service, ss ...service.HTTPOption) (*service.HTTPClient, error)
• func NewHTTPServiceServer(cfg *configv1.Service, ss ...service.HTTPOption) (*service.HTTPServer, error)
• func NewMiddlewareClient(name string, cm *middlewarev1.Middleware, ss ...middleware.Option) (middleware.KMiddleware, error)
• func NewMiddlewareServer(name string, cm *middlewarev1.Middleware, ss ...middleware.Option) (middleware.KMiddleware, error)
• func NewMiddlewaresClient(cc *middlewarev1.Middleware, ss ...middleware.Option) []middleware.KMiddleware
• func NewMiddlewaresServer(cc *middlewarev1.Middleware, ss ...middleware.Option) []middleware.KMiddleware
• func NewRegistrar(cfg *configv1.Discovery, ss ...registry.Option) (registry.KRegistrar, error)
• func RegisterConfig(name string, factory config.Factory)
• func RegisterConfigFunc(name string, buildFunc config.BuildFunc)
• func RegisterConfigSync(name string, syncFunc config.Syncer)
• func RegisterMiddleware(name string, builder middleware.Factory)
• func RegisterRegistry(name string, factory registry.Factory)
• func RegisterService(name string, factory service.ServerFactory)
• func SyncConfig(cfg *configv1.SourceConfig, v any, ss ...config.Option) error
• type Builder
  • func GlobalBuilder() Builder
  • func NewBuilder() Builder
• type Logger
• type Manager
• type MiddlewareBuildFunc
• type MiddlewareBuilder
• type MiddlewareBuilders
• type MiddlewareProvider
• type Option
  • func WithConfigOptions(options ...config.Option) Option
  • func WithContext(ctx context.Context) Option
  • func WithDefaultOptions() Option
  • func WithLogger(logger log.Logger) Option
  • func WithPrefix(prefix string) Option
  • func WithResolver(resolver config.Resolver) Option
  • func WithSignals(signals ...os.Signal) Option
• type Options
• type Runtime
  • func Global() Runtime
  • func Load(bs *bootstrap.Bootstrap, opts ...Option) (Runtime, error)
• type ServiceProvider
• type SignalHandler

Constants

const (
	DefaultEnvPrefix = "ORIGADMIN_RUNTIME_SERVICE"
)

Variables

var ErrNotFound = errors.String("not found")

ErrNotFound is an error that is returned when a ConfigBuilder or RegistryBuilder is not found.

Functions

func LoadConfig

func LoadConfig(path string, v any, ss ...config.Option) error

LoadConfig loads the config file from the given path

func LoadConfigFromBootstrap

func LoadConfigFromBootstrap(bs *bootstrap.Bootstrap, v any, ss ...config.Option) error

func NewConfig

func NewConfig(cfg *configv1.SourceConfig, ss ...config.Option) (config.KConfig, error)

NewConfig creates a new SelectorServer using the registered ConfigBuilder.

func NewDiscovery

func NewDiscovery(cfg *configv1.Discovery, ss ...registry.Option) (registry.KDiscovery, error)

NewDiscovery creates a new discovery using the registered RegistryBuilder.

func NewGRPCServiceClient

func NewGRPCServiceClient(ctx context.Context, cfg *configv1.Service, ss ...service.GRPCOption) (*service.GRPCClient, error)

NewGRPCServiceClient creates a new GRPC client using the provided context and configuration

func NewGRPCServiceServer

func NewGRPCServiceServer(cfg *configv1.Service, ss ...service.GRPCOption) (*service.GRPCServer, error)

NewGRPCServiceServer creates a new GRPC server using the provided configuration

func NewHTTPServiceClient

func NewHTTPServiceClient(ctx context.Context, cfg *configv1.Service, ss ...service.HTTPOption) (*service.HTTPClient, error)

NewHTTPServiceClient creates a new HTTP client using the provided context and configuration

func NewHTTPServiceServer

func NewHTTPServiceServer(cfg *configv1.Service, ss ...service.HTTPOption) (*service.HTTPServer, error)

NewHTTPServiceServer creates a new HTTP server using the provided configuration

func NewMiddlewareClient

func NewMiddlewareClient(name string, cm *middlewarev1.Middleware, ss ...middleware.Option) (middleware.KMiddleware, error)

NewMiddlewareClient creates a new KMiddleware with the builder.

func NewMiddlewareServer

func NewMiddlewareServer(name string, cm *middlewarev1.Middleware, ss ...middleware.Option) (middleware.KMiddleware, error)

NewMiddlewareServer creates a new KMiddleware with the builder.

func NewMiddlewaresClient

func NewMiddlewaresClient(cc *middlewarev1.Middleware, ss ...middleware.Option) []middleware.KMiddleware

NewMiddlewaresClient creates a new KMiddleware with the builder.

func NewMiddlewaresServer

func NewMiddlewaresServer(cc *middlewarev1.Middleware, ss ...middleware.Option) []middleware.KMiddleware

NewMiddlewaresServer creates a new KMiddleware with the builder.

func NewRegistrar

func NewRegistrar(cfg *configv1.Discovery, ss ...registry.Option) (registry.KRegistrar, error)

NewRegistrar creates a new KRegistrar using the registered RegistryBuilder.

func RegisterConfig

func RegisterConfig(name string, factory config.Factory)

RegisterConfig registers a ConfigBuilder with the builder.

func RegisterConfigFunc

func RegisterConfigFunc(name string, buildFunc config.BuildFunc)

RegisterConfigFunc registers a ConfigBuilder with the builder.

func RegisterConfigSync

func RegisterConfigSync(name string, syncFunc config.Syncer)

func RegisterMiddleware

func RegisterMiddleware(name string, builder middleware.Factory)

RegisterMiddleware registers a MiddlewareBuilder with the builder.

func RegisterRegistry

func RegisterRegistry(name string, factory registry.Factory)

RegisterRegistry registers a RegistryBuilder with the builder.

func RegisterService

func RegisterService(name string, factory service.ServerFactory)

RegisterService registers a service builder with the provided name

func SyncConfig

func SyncConfig(cfg *configv1.SourceConfig, v any, ss ...config.Option) error

SyncConfig synchronizes the given configuration with the given value.

Types

type Builder

type Builder interface {
	Config() config.Builder
	Registry() registry.Builder
	Service() service.ServerBuilder
	Middleware() middleware.Builder
	NewMiddlewareClient(name string, config *middlewarev1.Middleware, ss ...middleware.Option) (middleware.KMiddleware, error)
	NewMiddlewareServer(name string, config *middlewarev1.Middleware, ss ...middleware.Option) (middleware.KMiddleware, error)
	NewMiddlewaresClient(config *middlewarev1.Middleware, ss ...middleware.Option) []middleware.KMiddleware
	NewMiddlewaresServer(config *middlewarev1.Middleware, ss ...middleware.Option) []middleware.KMiddleware
	RegisterMiddlewareBuilder(name string, builder middleware.Factory)
	NewRegistrar(cfg *configv1.Discovery, ss ...registry.Option) (registry.KRegistrar, error)
	NewDiscovery(cfg *configv1.Discovery, ss ...registry.Option) (registry.KDiscovery, error)
	RegisterRegistryBuilder(name string, factory registry.Factory)
	RegisterRegistryFunc(name string, registryBuilder registry.RegistrarBuildFunc, discoveryBuilder registry.DiscoveryBuildFunc)
	NewConfig(sourceConfig *configv1.SourceConfig, options ...config.Option) (config.KConfig, error)
	RegisterConfigBuilder(s string, factory config.Factory)
	NewServer(name string, c *configv1.Service, options ...service.ServerOption) (transport.Server, error)
	NewGRPCServer(c *configv1.Service, options ...service.GRPCOption) (*service.GRPCServer, error)
	NewHTTPServer(c *configv1.Service, options ...service.HTTPOption) (*service.HTTPServer, error)
	NewGRPCClient(c context.Context, c2 *configv1.Service, options ...service.GRPCOption) (*service.GRPCClient, error)
	NewHTTPClient(c context.Context, c2 *configv1.Service, options ...service.HTTPOption) (*service.HTTPClient, error)
	RegisterServiceBuilder(name string, factory service.ServerFactory)
	SyncConfig(cfg *configv1.SourceConfig, v any, ss ...config.Option) error
	RegisterConfigSyncer(name string, configSyncer config.Syncer)
	RegisterConfigSync(name string, configSyncer config.Syncer)
}

func GlobalBuilder

func GlobalBuilder() Builder

GlobalBuilder returns the global Builder instance.

func NewBuilder

func NewBuilder() Builder

NewBuilder creates a new Builder.

type Logger

type Logger interface {
	Logger() log.KLogger
	SetLogger(kvs ...any)
	WithLogger(kvs ...any) log.KLogger
}

type Manager

type Manager struct {
	Middleware MiddlewareProvider
	Service    ServiceProvider
}

type MiddlewareBuildFunc

type MiddlewareBuildFunc = func(*configv1.Customize_Config, ...middleware.Option) (middleware.KMiddleware, error)

MiddlewareBuildFunc is an interface that defines methods for creating middleware.

type MiddlewareBuilder

type MiddlewareBuilder interface {
	// NewMiddlewareClient build middleware
	NewMiddlewareClient(*configv1.Customize_Config, ...middleware.Option) (middleware.KMiddleware, error)
	// NewMiddlewareServer build middleware
	NewMiddlewareServer(*configv1.Customize_Config, ...middleware.Option) (middleware.KMiddleware, error)
}

MiddlewareBuilder middleware builder interface

type MiddlewareBuilders

type MiddlewareBuilders interface {
	// NewMiddlewaresClient build middleware
	NewMiddlewaresClient(*middlewarev1.Middleware, ...middleware.Option) []middleware.KMiddleware
	// NewMiddlewaresServer build middleware
	NewMiddlewaresServer(*middlewarev1.Middleware, ...middleware.Option) []middleware.KMiddleware
	// NewMiddlewareClient build middleware
	NewMiddlewareClient(string, *middlewarev1.Middleware, ...middleware.Option) (middleware.KMiddleware, error)
	// NewMiddlewareServer build middleware
	NewMiddlewareServer(string, *middlewarev1.Middleware, ...middleware.Option) (middleware.KMiddleware, error)
}

MiddlewareBuilders middleware builders for runtime

type MiddlewareProvider

type MiddlewareProvider interface {
	BuildClient(cfg *middlewarev1.Middleware, opts ...middleware.Option) []middleware.KMiddleware
	BuildServer(cfg *middlewarev1.Middleware, opts ...middleware.Option) []middleware.KMiddleware
}

type Option

type Option func(*Options)

func WithConfigOptions

func WithConfigOptions(options ...config.Option) Option

func WithContext

func WithContext(ctx context.Context) Option

func WithDefaultOptions

func WithDefaultOptions() Option

func WithLogger

func WithLogger(logger log.Logger) Option

func WithPrefix

func WithPrefix(prefix string) Option

func WithResolver

func WithResolver(resolver config.Resolver) Option

func WithSignals

func WithSignals(signals ...os.Signal) Option

type Options

type Options struct {
	Context       context.Context
	Prefix        string
	ConfigOptions []config.Option
	Logger        log.Logger
	Signals       []os.Signal
	Resolver      config.Resolver
}

type Runtime

type Runtime interface {
	Logger
	SignalHandler
	Client() Runtime
	Builder() Builder
	Context() context.Context
	Load(opts ...config.Option) error
	CreateApp(...transport.Server) *kratos.App
	WithLoggerAttrs(kvs ...any) Runtime
	SetRegistry(registrar registry.KRegistrar)
}

func Global

func Global() Runtime

Global function returns the interface type

func Load

func Load(bs *bootstrap.Bootstrap, opts ...Option) (Runtime, error)

Load uses the global Runtime instance to load configurations and other resources with the provided bootstrap settings. It returns an error if the loading process fails.

type ServiceProvider

type ServiceProvider interface {
	CreateService(cfg *configv1.Service) (*kratos.App, error)
}

type SignalHandler

type SignalHandler interface {
	Signals() []os.Signal
	SetSignals([]os.Signal)
}