servicebase

README

Service Base

Yet another {micro,}service template, supporting HTTP and GRPC.

See cmd/sample for an example on how to use.

License

Copyright 2023 Zane van Iperen

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Documentation

Index

• Constants
• func GetRequestID(ctx context.Context) string
• func MakeStaticHandler(payload []byte, contentType string) http.Handler
• func MergeMap[T comparable, V any](left, right map[T]V) map[T]V
• func MergeString(left, right string) string
• func MethodNotAllowedHandler(w http.ResponseWriter, _ *http.Request)
• func NotFoundHandler(w http.ResponseWriter, _ *http.Request)
• func RunService(ctx context.Context, cfg ServiceConfig, factory ServiceFactory) error
• type FileMode
  • func (mode FileMode) MarshalText() ([]byte, error)
  • func (mode *FileMode) UnmarshalText(data []byte) error
• type GRPCConfig
  • func DefaultGRPCConfig() GRPCConfig
  • func MergeGRPCConfig(left, right *GRPCConfig) *GRPCConfig
  • func (cfg *GRPCConfig) Flags() []cli.Flag
• type GetHealthResponse
• type HTTPConfig
  • func DefaultHTTPConfig() HTTPConfig
  • func MergeHTTPConfig(left, right *HTTPConfig) *HTTPConfig
  • func (cfg *HTTPConfig) Flags() []cli.Flag
• type HTTPHealthResponse
  • func (r *HTTPHealthResponse) ServeHTTP(w http.ResponseWriter, _ *http.Request)
• type HTTPHealthStatus
• type HealthCheckable
• type HealthStatus
• type ListenConfig
  • func MergeListenConfig(left, right *ListenConfig) *ListenConfig
• type LogFormat
• type Metrics
  • func (m *Metrics) RecordHTTPRequest(req *http.Request)
• type Service
• type ServiceConfig
  • func DefaultServiceConfig() ServiceConfig
  • func MergeServiceConfig(left, right *ServiceConfig) *ServiceConfig
  • func (cfg *ServiceConfig) Flags() []cli.Flag
• type ServiceFactory
• type ServiceParameters

Constants

const (
	HTTPHealthStatusPass = "pass"
	HTTPHealthStatusFail = "fail"
	HTTPHealthStatusWarn = "warn"
)

const (
	ContentTypeTextPlainUTF8       = "text/plain; charset=utf-8"
	ContentTypeApplicationJSONUTF8 = "application/json; charset=utf-8"
)

const (
	LogFormatText = "text"
	LogFormatJSON = "json"
)

Functions

func GetRequestID

func GetRequestID(ctx context.Context) string

func MakeStaticHandler

func MakeStaticHandler(payload []byte, contentType string) http.Handler

func MergeMap

func MergeMap[T comparable, V any](left, right map[T]V) map[T]V

func MergeString

func MergeString(left, right string) string

func MethodNotAllowedHandler

func MethodNotAllowedHandler(w http.ResponseWriter, _ *http.Request)

func NotFoundHandler

func NotFoundHandler(w http.ResponseWriter, _ *http.Request)

func RunService

func RunService(ctx context.Context, cfg ServiceConfig, factory ServiceFactory) error

Types

type FileMode

type FileMode fs.FileMode

FileMode is a wrapper for fs.FileMode that supports serialisation

func (FileMode) MarshalText

func (mode FileMode) MarshalText() ([]byte, error)

func (*FileMode) UnmarshalText

func (mode *FileMode) UnmarshalText(data []byte) error

type GRPCConfig

type GRPCConfig struct {
	ListenConfig
	DisableMetrics   bool                `json:"disable_metrics"`
	EnableReflection bool                `json:"enable_reflection"`
	Options          []grpc.ServerOption `json:"-"` // TODO: Make this configurable from JSON/command line
	// contains filtered or unexported fields
}

func DefaultGRPCConfig

func DefaultGRPCConfig() GRPCConfig

func MergeGRPCConfig

func MergeGRPCConfig(left, right *GRPCConfig) *GRPCConfig

func (*GRPCConfig) Flags

func (cfg *GRPCConfig) Flags() []cli.Flag

type GetHealthResponse

type GetHealthResponse struct {
	Status       HealthStatus                  `json:"status"`
	Message      string                        `json:"message"`
	Dependencies map[string]*GetHealthResponse `json:"dependencies"`
}

type HTTPConfig

type HTTPConfig struct {
	ListenConfig
	PathPrefix        string        `json:"path_prefix,omitempty"`
	DisableXFF        bool          `json:"disable_xff,omitempty"`
	DisableMetrics    bool          `json:"disable_metrics"`
	DisableHealth     bool          `json:"disable_health"`
	ReadHeaderTimeout time.Duration `json:"read_header_timeout"`
	// contains filtered or unexported fields
}

func DefaultHTTPConfig

func DefaultHTTPConfig() HTTPConfig

func MergeHTTPConfig

func MergeHTTPConfig(left, right *HTTPConfig) *HTTPConfig

func (*HTTPConfig) Flags

func (cfg *HTTPConfig) Flags() []cli.Flag

type HTTPHealthResponse

type HTTPHealthResponse struct {
	Status HTTPHealthStatus `json:"status"`
	Notes  []string         `json:"notes,omitempty"`
	Output string           `json:"output,omitempty"`
}

https://www.ietf.org/archive/id/draft-inadarei-api-health-check-06.html

func (*HTTPHealthResponse) ServeHTTP

func (r *HTTPHealthResponse) ServeHTTP(w http.ResponseWriter, _ *http.Request)

type HTTPHealthStatus

type HTTPHealthStatus string

type HealthCheckable

type HealthCheckable interface {
	GetHealth(ctx context.Context) (*GetHealthResponse, error)
}

type HealthStatus

type HealthStatus string

const (
	HealthStatusUnknown   HealthStatus = "unknown"
	HealthStatusHealthy   HealthStatus = "healthy"
	HealthStatusDegraded  HealthStatus = "degraded"
	HealthStatusUnhealthy HealthStatus = "unhealthy"
)

type ListenConfig

type ListenConfig struct {
	Enabled           bool     `json:"enabled"`
	BindAddress       string   `json:"bind_address,omitempty"`
	BindNetwork       string   `json:"bind_network,omitempty"`
	SocketPermissions FileMode `json:"socket_permissions,omitempty"`
	// contains filtered or unexported fields
}

func MergeListenConfig

func MergeListenConfig(left, right *ListenConfig) *ListenConfig

type LogFormat

type LogFormat string

type Metrics

type Metrics struct {
	Registry *prometheus.Registry
	// contains filtered or unexported fields
}

func (*Metrics) RecordHTTPRequest

func (m *Metrics) RecordHTTPRequest(req *http.Request)

type Service

type Service interface {
	HealthCheckable

	Close(ctx context.Context) error
}

type ServiceConfig

type ServiceConfig struct {
	LogLevel         slog.Level    `json:"log_level,omitempty"`
	LogFormat        string        `json:"log_format,omitempty"`
	ShutdownTimeout  time.Duration `json:"shutdown_timeout"`
	HTTP             HTTPConfig    `json:"http"`
	GRPC             GRPCConfig    `json:"grpc"`
	DisableRequestID bool          `json:"disable_request_id"`
	// contains filtered or unexported fields
}

func DefaultServiceConfig

func DefaultServiceConfig() ServiceConfig

func MergeServiceConfig

func MergeServiceConfig(left, right *ServiceConfig) *ServiceConfig

func (*ServiceConfig) Flags

func (cfg *ServiceConfig) Flags() []cli.Flag

type ServiceFactory

type ServiceFactory func(ctx context.Context, params ServiceParameters) (Service, error)

type ServiceParameters

type ServiceParameters struct {
	Logger  *slog.Logger
	Metrics Metrics

	// ServiceRouter is the top-level HTTP router, without the path prefix applied.
	ServiceRouter *mux.Router

	// ApplicationRouter is the application-level HTTP router, with the path prefix applied.
	ApplicationRouter *mux.Router

	// GRPCRegistrar is the GRPC service registrar.
	GRPCRegistrar grpc.ServiceRegistrar
}