README
¶
Telestion Service Framework for Go
This library provides a framework for building Telestion services in Go.
Installation
Install the library via go get:
go get -u github.com/wuespace/telestion/backend-go@latest
Basic Usage
package main
import (
"github.com/wuespace/telestion/backend-go"
"log"
)
type Person struct {
Name string `json:"name"`
Address string `json:"address"`
}
func main() {
// start a new Telestion service
service, err := telestion.StartService()
if err != nil {
log.Fatal(err)
}
log.Println("Service started")
// publish a message on the message bus
service.Nc.Publish("my-topic", []byte("Hello from Go!"))
// subscribe to receive messages from the message bus
// automatically unmarshal JSON message to go struct
_, err = service.NcJson.Subscribe("registered-person-topic", func(person *Person) {
log.Println("Received new personal information:", person)
})
if err != nil {
log.Println(err)
}
// wait for interrupts to prevent immediate shutdown of service
telestion.WaitForInterrupt()
// drain remaining messages and close connection
if err1, err2 := service.Drain(); err1 != nil || err2 != nil {
log.Fatal(err1, err2)
}
}
Behavior Specification
The behavior of this library is specified in
the Behavior Specification.
This specification is also used to test the library.
The source code of the tests can be found in the repository under /backend-features.
License
This project is licensed under the terms of the MIT license.
Documentation
¶
Overview ¶
Package telestion provides a framework for building Telestion services in Go.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WaitForInterrupt ¶
WaitForInterrupt blocks the execution of the current goroutine. It waits for a process interrupt and returns the detected signal to the caller.
Example ¶
The WaitForInterrupt function waits for an external interrupt to prevent immediate shutdown of the service.
// start a new Telestion service
service, _ := telestion.StartService()
// subscribe to a subject on the message bus
_, _ = service.Nc.Subscribe("subject", func(msg *nats.Msg) {
//...
})
// wait for external interrupt to prevent immediate shutdown of service
telestion.WaitForInterrupt()
// drain NATS connections
_, _ = service.Drain()
Output:
Types ¶
type Config ¶
type Config struct {
// Dev if enabled, adds minimal required configuration parameters to the configuration object.
Dev bool `mapstructure:"DEV"`
// NatsUrl describes the url that NATS uses to connect to the NATS server.
NatsUrl string `mapstructure:"NATS_URL"`
// NatsUser is the username that the NATS client uses to log in on the NATS server.
// This property can be undefined (empty) if no configuration source provided this parameter.
NatsUser string `mapstructure:"NATS_USER"`
// NatsPassword is the password that the NATS client uses to log in on the NATS server.
// This property can be undefined (empty) if no configuration source provided this parameter.
NatsPassword string `mapstructure:"NATS_PASSWORD"`
// ConfigFile contains the path to the configuration file that [StartService] reads during startup.
// This property can be undefined (empty) if no configuration source provided this parameter.
ConfigFile string `mapstructure:"CONFIG_FILE"`
// ConfigKey describes a key in config file's root object that configures this service.
// This property can be undefined if no configuration source provided this parameter.
ConfigKey string `mapstructure:"CONFIG_KEY"`
// ServiceName contains the name of the service.
// This is used to create a unique queue group for the service and support running multiple
// parallel instances.
ServiceName string `mapstructure:"SERVICE_NAME"`
// DataDir is the path to the data directory.
// This is where the service should store any data it needs to persist.
// The data is shared between multiple services.
// To ensure that the service doesn't overwrite data from other services,
// you should create a subdirectory for your service.
DataDir string `mapstructure:"DATA_DIR"`
// CustomConfig contains unparsed configuration from all configuration sources.
// To use these configuration parameter you need to type cast these to a suitable type.
CustomConfig map[string]any `json:"-" ,mapstructure:",remain"`
}
Config configures the Telestion service. The parsed configuration returned from the startService function for further usage.
type Option ¶
Option takes the startup options from StartService and modifies the startup behaviour.
func WithCustomNc ¶
func WithCustomNc(nc *nats.Conn, ncJson *nats.EncodedConn) Option
WithCustomNc gives StartService externally managed NATS connections. This option prevents StartService to initialize another NATS connection. Both arguments must be a valid NATS connection.
func WithOverwriteArgs ¶
WithOverwriteArgs passes additional configuration parameters to StartService. These parameters have precedence over any other configuration source.
func WithoutNats ¶
func WithoutNats() Option
WithoutNats disables the NATS initialization step in StartService.
type Options ¶
type Options struct {
// Nats instructs [StartService] whether a NATS connection should be initialized.
Nats bool
// OverwriteArgs provides additional configuration parameters
// that have precedence over any other configuration source.
OverwriteArgs map[string]string
// CustomNc is a NATS connection that is externally managed and passed to [StartService] during startup.
// If `CustomNc != nil` [StartService] does not create another NATS connection
// and uses the provided connection instead.
// Used for testing.
CustomNc *nats.Conn
// CustomNcJson is an abstraction of [Options.CustomNc].
// It provides automatic JSON marshaling and unmarshalling of NATS message bodies.
// Used for testing.
CustomNcJson *nats.EncodedConn
}
Options describes the different options Option can change to modify the startup behaviour of StartService.
type Service ¶
type Service struct {
// Nc is the NATS connection the service uses to communicate with other services on the NATS network.
Nc *nats.Conn
// NcJson is an abstraction of [Service.Nc]
// that provides automatic JSON marshaling and unmarshalling of NATS message bodies.
NcJson *nats.EncodedConn
// DataDir is an absolute path to the data directory of the service.
// This is where the service should store any data it needs to persist.
// The data is shared between multiple services.
// To ensure that the service doesn't overwrite data from other services,
// you should create a subdirectory for your service.
DataDir string
// ServiceName is the name of the service.
// This is used to create a unique queue group for the service.
ServiceName string
// Config is the assembled configuration from all available configuration sources.
// It configures the service.
Config *Config
}
Service is a Telestion service that provides the available APIs.
func StartService ¶
StartService starts a new Telestion service and returns the available APIs. Additional options passed are applied in the order in they appear and modify the startup procedure.
During startup the service parses the service Config from different configuration sources with the following priorities:
- `overwriteArgs` from WithOverwriteArgs
- command line arguments
- environment variables
- default configuration, if `--dev` is passed in the steps from above
- configuration file, if `CONFIG_FILE` parameter is defined, readable and parsable
Source Files
Directories