Initial QSfera import

Server/services/nats/Makefile

@@ -0,0 +1,11 @@
+SHELL := bash
+NAME := nats
+
+ifneq (, $(shell command -v go 2> /dev/null)) # suppress `command not found warnings` for non go targets in CI
+include ../../.bingo/Variables.mk
+endif
+
+include ../../.make/default.mk
+include ../../.make/go.mk
+include ../../.make/release.mk
+include ../../.make/docs.mk

Server/services/nats/README.md

@@ -0,0 +1,25 @@
+# Nats
+
+The nats service is the event broker of the system. It distributes events among all other services and enables other services to communicate asynchronous.
+
+Services can `Publish` events to the nats service and nats will store these events on disk and distribute these events to other services eventually. Services can `Consume` events from the nats service by registering to a `ConsumerGroup`. Each `ConsumerGroup` is guaranteed to get each event exactly once. In most cases, each service will register its own `ConsumerGroup`. When there are multiple instances of a service, those instances will usually use that `ConsumerGroup` as common resource.
+
+## Underlying Technology
+
+As the service name suggests, this service is based on [NATS](https://nats.io/) specifically on [NATS Jetstream](https://docs.nats.io/nats-concepts/jetstream) to enable persistence.
+
+## Default Registry
+
+By default, `nats-js-kv` is configured as embedded default registry via the `MICRO_REGISTRY` environment variable. If you do not want using the build-in nats registry, set `MICRO_REGISTRY_ADDRESS` to the address of the nats-js cluster, which is the same value as `OC_EVENTS_ENDPOINT`. Optionally use `MICRO_REGISTRY_AUTH_USERNAME` and `MICRO_REGISTRY_AUTH_PASSWORD` to authenticate with the external nats cluster.
+
+## Persistance
+
+To be able to deliver events even after a system or service restart, nats will store events in a folder on the local filesystem. This folder can be specified by setting the `NATS_NATS_STORE_DIR` enviroment variable. If not set, the service will fall back to `$OC_BASE_DATA_PATH/nats`.
+
+## TLS Encryption
+
+Connections to the nats service (`Publisher`/`Consumer` see above) can be TLS encrypted by setting the corresponding env vars `NATS_TLS_CERT`, `NATS_TLS_KEY` to the cert and key files and `ENABLE_TLS` to true. Checking the certificate of incoming request can be disabled with the `NATS_EVENTS_ENABLE_TLS` environment variable.
+
+Certificate files can also be set via global variables starting with `OC_`, for details see the environment variable list.
+
+Note that using TLS is highly recommended for productive environments, especially when using container orchestration with Kubernetes.

Server/services/nats/pkg/command/health.go

@@ -0,0 +1,19 @@
+package command
+
+import (
+	"github.com/qsfera/server/services/nats/pkg/config"
+
+	"github.com/spf13/cobra"
+)
+
+// Health is the entrypoint for the health command.
+func Health(cfg *config.Config) *cobra.Command {
+	return &cobra.Command{
+		Use:   "health",
+		Short: "Check health status",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			// Not implemented
+			return nil
+		},
+	}
+}

Server/services/nats/pkg/command/root.go

@@ -0,0 +1,36 @@
+package command
+
+import (
+	"os"
+
+	"github.com/qsfera/server/pkg/clihelper"
+	"github.com/qsfera/server/services/nats/pkg/config"
+
+	"github.com/spf13/cobra"
+)
+
+// GetCommands provides all commands for this service
+func GetCommands(cfg *config.Config) []*cobra.Command {
+	return []*cobra.Command{
+		// start this service
+		Server(cfg),
+
+		// interaction with this service
+
+		// infos about this service
+		Health(cfg),
+		Version(cfg),
+	}
+}
+
+// Execute is the entry point for the nats command.
+func Execute(cfg *config.Config) error {
+	app := clihelper.DefaultApp(&cobra.Command{
+		Use:   "nats",
+		Short: "starts nats server",
+	})
+	app.AddCommand(GetCommands(cfg)...)
+	app.SetArgs(os.Args[1:])
+
+	return app.ExecuteContext(cfg.Context)
+}

Server/services/nats/pkg/command/server.go

@@ -0,0 +1,110 @@
+package command
+
+import (
+	"context"
+	"crypto/tls"
+	"fmt"
+	"os/signal"
+
+	"github.com/qsfera/server/pkg/config/configlog"
+	pkgcrypto "github.com/qsfera/server/pkg/crypto"
+	"github.com/qsfera/server/pkg/log"
+	"github.com/qsfera/server/pkg/runner"
+	"github.com/qsfera/server/services/nats/pkg/config"
+	"github.com/qsfera/server/services/nats/pkg/config/parser"
+	"github.com/qsfera/server/services/nats/pkg/logging"
+	"github.com/qsfera/server/services/nats/pkg/server/debug"
+	"github.com/qsfera/server/services/nats/pkg/server/nats"
+
+	"github.com/spf13/cobra"
+)
+
+// Server is the entrypoint for the server command.
+func Server(cfg *config.Config) *cobra.Command {
+	return &cobra.Command{
+		Use:   "server",
+		Short: fmt.Sprintf("start the %s service without runtime (unsupervised mode)", cfg.Service.Name),
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			return configlog.ReturnFatal(parser.ParseConfig(cfg))
+		},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			logger := log.Configure(cfg.Service.Name, cfg.Commons, cfg.LogLevel)
+
+			var cancel context.CancelFunc
+			if cfg.Context == nil {
+				cfg.Context, cancel = signal.NotifyContext(context.Background(), runner.StopSignals...)
+				defer cancel()
+			}
+			ctx := cfg.Context
+
+			gr := runner.NewGroup()
+			{
+				debugServer, err := debug.Server(
+					debug.Logger(logger),
+					debug.Context(ctx),
+					debug.Config(cfg),
+				)
+				if err != nil {
+					logger.Info().Err(err).Str("transport", "debug").Msg("Failed to initialize server")
+					return err
+				}
+
+				gr.Add(runner.NewGolangHttpServerRunner(cfg.Service.Name+".debug", debugServer))
+			}
+
+			var tlsConf *tls.Config
+			if cfg.Nats.EnableTLS {
+				// Generate a self-signing cert if no certificate is present
+				if err := pkgcrypto.GenCert(cfg.Nats.TLSCert, cfg.Nats.TLSKey, logger); err != nil {
+					logger.Fatal().Err(err).Msgf("Could not generate test-certificate")
+				}
+
+				crt, err := tls.LoadX509KeyPair(cfg.Nats.TLSCert, cfg.Nats.TLSKey)
+				if err != nil {
+					return err
+				}
+
+				clientAuth := tls.RequireAndVerifyClientCert
+				if cfg.Nats.TLSSkipVerifyClientCert {
+					clientAuth = tls.NoClientCert
+				}
+
+				tlsConf = &tls.Config{
+					MinVersion:   tls.VersionTLS12,
+					ClientAuth:   clientAuth,
+					Certificates: []tls.Certificate{crt},
+				}
+			}
+			natsServer, err := nats.NewNATSServer(
+				logging.NewLogWrapper(logger),
+				nats.Host(cfg.Nats.Host),
+				nats.Port(cfg.Nats.Port),
+				nats.ClusterID(cfg.Nats.ClusterID),
+				nats.StoreDir(cfg.Nats.StoreDir),
+				nats.TLSConfig(tlsConf),
+				nats.AllowNonTLS(!cfg.Nats.EnableTLS),
+			)
+			if err != nil {
+				return err
+			}
+
+			gr.Add(runner.New(cfg.Service.Name+".svc", func() error {
+				return natsServer.ListenAndServe()
+			}, func() {
+				logger.Info().Msg("Gracefully shutting down the NATS server...")
+				natsServer.Shutdown()
+				logger.Info().Msg("NATS server shutdown")
+			}))
+
+			grResults := gr.Run(ctx)
+
+			// return the first non-nil error found in the results
+			for _, grResult := range grResults {
+				if grResult.RunnerError != nil {
+					return grResult.RunnerError
+				}
+			}
+			return nil
+		},
+	}
+}

Server/services/nats/pkg/command/version.go

@@ -0,0 +1,19 @@
+package command
+
+import (
+	"github.com/qsfera/server/services/nats/pkg/config"
+
+	"github.com/spf13/cobra"
+)
+
+// Version prints the service versions of all running instances.
+func Version(cfg *config.Config) *cobra.Command {
+	return &cobra.Command{
+		Use:   "version",
+		Short: "print the version of this binary and the running service instances",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			// not implemented
+			return nil
+		},
+	}
+}

Server/services/nats/pkg/config/config.go

@@ -0,0 +1,31 @@
+package config
+
+import (
+	"context"
+
+	"github.com/qsfera/server/pkg/shared"
+)
+
+// Config combines all available configuration parts.
+type Config struct {
+	Commons  *shared.Commons `yaml:"-"` // don't use this directly as configuration for a service
+	Service  Service         `yaml:"-"`
+	LogLevel string          `yaml:"loglevel" env:"OC_LOG_LEVEL;NATS_LOG_LEVEL" desc:"The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'." introductionVersion:"1.0.0"`
+	Debug    Debug           `yaml:"debug"`
+
+	Nats Nats `ociConfig:"nats"`
+
+	Context context.Context `yaml:"-"`
+}
+
+// Nats is the nats config
+type Nats struct {
+	Host                    string `yaml:"host" env:"NATS_NATS_HOST" desc:"Bind address." introductionVersion:"1.0.0"`
+	Port                    int    `yaml:"port" env:"NATS_NATS_PORT" desc:"Bind port." introductionVersion:"1.0.0"`
+	ClusterID               string `yaml:"clusterid" env:"NATS_NATS_CLUSTER_ID" desc:"ID of the NATS cluster." introductionVersion:"1.0.0"`
+	StoreDir                string `yaml:"store_dir" env:"NATS_NATS_STORE_DIR" desc:"The directory where the filesystem storage will store NATS JetStream data. If not defined, the root directory derives from $OC_BASE_DATA_PATH/nats." introductionVersion:"1.0.0"`
+	TLSCert                 string `yaml:"tls_cert" env:"NATS_TLS_CERT" desc:"Path/File name of the TLS server certificate (in PEM format) for the NATS listener. If not defined, the root directory derives from $OC_BASE_DATA_PATH/nats." introductionVersion:"1.0.0"`
+	TLSKey                  string `yaml:"tls_key" env:"NATS_TLS_KEY" desc:"Path/File name for the TLS certificate key (in PEM format) for the NATS listener. If not defined, the root directory derives from $OC_BASE_DATA_PATH/nats." introductionVersion:"1.0.0"`
+	TLSSkipVerifyClientCert bool   `yaml:"tls_skip_verify_client_cert" env:"OC_INSECURE;NATS_TLS_SKIP_VERIFY_CLIENT_CERT" desc:"Whether the NATS server should skip the client certificate verification during the TLS handshake." introductionVersion:"1.0.0"`
+	EnableTLS               bool   `yaml:"enable_tls" env:"OC_EVENTS_ENABLE_TLS;NATS_EVENTS_ENABLE_TLS" desc:"Enable TLS for the connection to the events broker. The events broker is the КуСфера service which receives and delivers events between the services." introductionVersion:"1.0.0"`
+}

Server/services/nats/pkg/config/debug.go

@@ -0,0 +1,9 @@
+package config
+
+// Debug defines the available debug configuration.
+type Debug struct {
+	Addr   string `yaml:"addr" env:"NATS_DEBUG_ADDR" desc:"Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed." introductionVersion:"1.0.0"`
+	Token  string `yaml:"token" env:"NATS_DEBUG_TOKEN" desc:"Token to secure the metrics endpoint." introductionVersion:"1.0.0"`
+	Pprof  bool   `yaml:"pprof" env:"NATS_DEBUG_PPROF" desc:"Enables pprof, which can be used for profiling." introductionVersion:"1.0.0"`
+	Zpages bool   `yaml:"zpages" env:"NATS_DEBUG_ZPAGES" desc:"Enables zpages, which can be used for collecting and viewing in-memory traces." introductionVersion:"1.0.0"`
+}

Server/services/nats/pkg/config/defaults/defaultconfig.go

@@ -0,0 +1,55 @@
+package defaults
+
+import (
+	"path/filepath"
+
+	"github.com/qsfera/server/pkg/config/defaults"
+	"github.com/qsfera/server/services/nats/pkg/config"
+)
+
+// NOTE: Most of this configuration is not needed to keep it as simple as possible
+// TODO: Clean up unneeded configuration
+
+// FullDefaultConfig returns a fully initialized default configuration
+func FullDefaultConfig() *config.Config {
+	cfg := DefaultConfig()
+	EnsureDefaults(cfg)
+	Sanitize(cfg)
+	return cfg
+}
+
+// DefaultConfig returns a basic default configuration
+func DefaultConfig() *config.Config {
+	return &config.Config{
+		Debug: config.Debug{
+			Addr:   "127.0.0.1:9234",
+			Token:  "",
+			Pprof:  false,
+			Zpages: false,
+		},
+		Service: config.Service{
+			Name: "nats",
+		},
+		Nats: config.Nats{
+			Host:      "127.0.0.1",
+			Port:      9233,
+			ClusterID: "qsfera-cluster",
+			StoreDir:  filepath.Join(defaults.BaseDataPath(), "nats"),
+			TLSCert:   filepath.Join(defaults.BaseDataPath(), "nats/tls.crt"),
+			TLSKey:    filepath.Join(defaults.BaseDataPath(), "nats/tls.key"),
+			EnableTLS: false,
+		},
+	}
+}
+
+// EnsureDefaults adds default values to the configuration if they are not set yet
+func EnsureDefaults(cfg *config.Config) {
+	if cfg.LogLevel == "" {
+		cfg.LogLevel = "error"
+	}
+}
+
+// Sanitize sanitizes the configuration
+func Sanitize(cfg *config.Config) {
+	// nothing to sanitize here atm
+}

Server/services/nats/pkg/config/parser/parse.go

@@ -0,0 +1,37 @@
+package parser
+
+import (
+	"errors"
+
+	occfg "github.com/qsfera/server/pkg/config"
+	"github.com/qsfera/server/services/nats/pkg/config"
+	"github.com/qsfera/server/services/nats/pkg/config/defaults"
+
+	"github.com/qsfera/server/pkg/config/envdecode"
+)
+
+// ParseConfig loads configuration from known paths.
+func ParseConfig(cfg *config.Config) error {
+	err := occfg.BindSourcesToStructs(cfg.Service.Name, cfg)
+	if err != nil {
+		return err
+	}
+
+	defaults.EnsureDefaults(cfg)
+
+	// load all env variables relevant to the config in the current context.
+	if err := envdecode.Decode(cfg); err != nil {
+		// no environment variable set for this config is an expected "error"
+		if !errors.Is(err, envdecode.ErrNoTargetFieldsAreSet) {
+			return err
+		}
+	}
+
+	defaults.Sanitize(cfg)
+
+	return Validate(cfg)
+}
+
+func Validate(cfg *config.Config) error {
+	return nil
+}

Server/services/nats/pkg/config/service.go

@@ -0,0 +1,6 @@
+package config
+
+// Service defines the available service configuration.
+type Service struct {
+	Name string `yaml:"-"`
+}

Server/services/nats/pkg/logging/nats.go

@@ -0,0 +1,52 @@
+package logging
+
+import (
+	"fmt"
+
+	"github.com/qsfera/server/pkg/log"
+)
+
+func NewLogWrapper(logger log.Logger) *LogWrapper {
+	return &LogWrapper{logger}
+}
+
+// we need to wrap our logger so we can pass it to the nats server
+type LogWrapper struct {
+	logger log.Logger
+}
+
+// Noticef logs a notice statement
+func (l *LogWrapper) Noticef(format string, v ...any) {
+	msg := fmt.Sprintf(format, v...)
+	l.logger.Info().Msg(msg)
+}
+
+// Warnf logs a warning statement
+func (l *LogWrapper) Warnf(format string, v ...any) {
+	msg := fmt.Sprintf(format, v...)
+	l.logger.Warn().Msg(msg)
+}
+
+// Fatalf logs a fatal statement
+func (l *LogWrapper) Fatalf(format string, v ...any) {
+	msg := fmt.Sprintf(format, v...)
+	l.logger.Fatal().Msg(msg)
+}
+
+// Errorf logs an error statement
+func (l *LogWrapper) Errorf(format string, v ...any) {
+	msg := fmt.Sprintf(format, v...)
+	l.logger.Error().Msg(msg)
+}
+
+// Debugf logs a debug statement
+func (l *LogWrapper) Debugf(format string, v ...any) {
+	msg := fmt.Sprintf(format, v...)
+	l.logger.Debug().Msg(msg)
+}
+
+// Tracef logs a trace statement
+func (l *LogWrapper) Tracef(format string, v ...any) {
+	msg := fmt.Sprintf(format, v...)
+	l.logger.Trace().Msg(msg)
+}

Server/services/nats/pkg/server/debug/option.go

@@ -0,0 +1,50 @@
+package debug
+
+import (
+	"context"
+
+	"github.com/qsfera/server/pkg/log"
+	"github.com/qsfera/server/services/nats/pkg/config"
+)
+
+// Option defines a single option function.
+type Option func(o *Options)
+
+// Options defines the available options for this package.
+type Options struct {
+	Logger  log.Logger
+	Context context.Context
+	Config  *config.Config
+}
+
+// newOptions initializes the available default options.
+func newOptions(opts ...Option) Options {
+	opt := Options{}
+
+	for _, o := range opts {
+		o(&opt)
+	}
+
+	return opt
+}
+
+// Logger provides a function to set the logger option.
+func Logger(val log.Logger) Option {
+	return func(o *Options) {
+		o.Logger = val
+	}
+}
+
+// Context provides a function to set the context option.
+func Context(val context.Context) Option {
+	return func(o *Options) {
+		o.Context = val
+	}
+}
+
+// Config provides a function to set the config option.
+func Config(val *config.Config) Option {
+	return func(o *Options) {
+		o.Config = val
+	}
+}

Server/services/nats/pkg/server/debug/server.go

@@ -0,0 +1,36 @@
+package debug
+
+import (
+	"net/http"
+	"strconv"
+
+	"github.com/qsfera/server/pkg/checks"
+	"github.com/qsfera/server/pkg/handlers"
+	"github.com/qsfera/server/pkg/service/debug"
+	"github.com/qsfera/server/pkg/version"
+)
+
+// Server initializes the debug service and server.
+func Server(opts ...Option) (*http.Server, error) {
+	options := newOptions(opts...)
+
+	// For nats readiness and liveness checks are identical
+	// the nats server will neither be healthy nor ready when it can not reach the nats server/cluster
+	checkHandler := handlers.NewCheckHandler(
+		handlers.NewCheckHandlerConfiguration().
+			WithLogger(options.Logger).
+			WithCheck("nats reachability", checks.NewNatsCheck(options.Config.Nats.Host+":"+strconv.Itoa(options.Config.Nats.Port))),
+	)
+
+	return debug.NewService(
+		debug.Logger(options.Logger),
+		debug.Name(options.Config.Service.Name),
+		debug.Version(version.GetString()),
+		debug.Address(options.Config.Debug.Addr),
+		debug.Token(options.Config.Debug.Token),
+		debug.Pprof(options.Config.Debug.Pprof),
+		debug.Zpages(options.Config.Debug.Zpages),
+		debug.Health(checkHandler),
+		debug.Ready(checkHandler),
+	), nil
+}

Server/services/nats/pkg/server/nats/nats.go

@@ -0,0 +1,51 @@
+package nats
+
+import (
+	"time"
+
+	nserver "github.com/nats-io/nats-server/v2/server"
+)
+
+var NATSListenAndServeLoopTimer = 1 * time.Second
+
+type NATSServer struct {
+	server *nserver.Server
+}
+
+// NatsOption configures the new NATSServer instance
+func NewNATSServer(logger nserver.Logger, opts ...NatsOption) (*NATSServer, error) {
+	natsOpts := &nserver.Options{}
+
+	for _, o := range opts {
+		o(natsOpts)
+	}
+
+	// enable JetStream
+	natsOpts.JetStream = true
+	// The NATS server itself runs the signal handling. We set `natsOpts.NoSigs = true` because we want to handle signals ourselves
+	natsOpts.NoSigs = true
+
+	server, err := nserver.NewServer(natsOpts)
+	if err != nil {
+		return nil, err
+	}
+
+	server.SetLoggerV2(logger, true, true, false)
+
+	return &NATSServer{
+		server: server,
+	}, nil
+}
+
+// ListenAndServe runs the NATSServer in a blocking way until the server is shutdown or an error occurs
+func (n *NATSServer) ListenAndServe() (err error) {
+	n.server.Start()           // it won't block
+	n.server.WaitForShutdown() // block until the server is fully shutdown
+	return nil
+}
+
+// Shutdown stops the NATSServer gracefully
+func (n *NATSServer) Shutdown() {
+	n.server.Shutdown()
+	n.server.WaitForShutdown()
+}

Server/services/nats/pkg/server/nats/options.go

@@ -0,0 +1,52 @@
+package nats
+
+import (
+	"crypto/tls"
+
+	nserver "github.com/nats-io/nats-server/v2/server"
+)
+
+// NatsOption configures the nats server
+type NatsOption func(*nserver.Options)
+
+// Host sets the host URL for the nats server
+func Host(url string) NatsOption {
+	return func(o *nserver.Options) {
+		o.Host = url
+	}
+}
+
+// Port sets the host URL for the nats server
+func Port(port int) NatsOption {
+	return func(o *nserver.Options) {
+		o.Port = port
+	}
+}
+
+// ClusterID sets the name for the nats cluster
+func ClusterID(clusterID string) NatsOption {
+	return func(o *nserver.Options) {
+		o.Cluster.Name = clusterID
+	}
+}
+
+// StoreDir sets the folder for persistence
+func StoreDir(StoreDir string) NatsOption {
+	return func(o *nserver.Options) {
+		o.StoreDir = StoreDir
+	}
+}
+
+// TLSConfig sets the tls config for the nats server
+func TLSConfig(c *tls.Config) NatsOption {
+	return func(o *nserver.Options) {
+		o.TLSConfig = c
+	}
+}
+
+// AllowNonTLS sets the allow non tls options for the nats server
+func AllowNonTLS(v bool) NatsOption {
+	return func(o *nserver.Options) {
+		o.AllowNonTLS = v
+	}
+}