oakserver

Documentation

Overview

Package oakserver provides a standard library http.Server with conventional production defaults and a smooth configuration interface.

Standard Usage

err := oakserver.Run(context.Background())

NGrok Usage

OakServer is easy to use with <https://ngrok.com> tunnel, which exposes your local server to the world. Use with caution. You should be fairly confident that your code is secure and will not leak data from your system or damage it.

import (
  // ...
  "golang.ngrok.com/ngrok"
  "golang.ngrok.com/ngrok/config"
)

func main() {
  // ...
  tunnel, err := ngrok.Listen(ctx,
    config.HTTPEndpoint(),
    ngrok.WithAuthtokenFromEnv(),
  )
  if err != nil {
    panic(err)
  }

  fmt.Println("NGrok HTTP endpoint:", tunnel.URL())
  err := oakserver.Run(
    context.Background(),
    oakserver.WithListener(tunnel),
  )
  // ...
}

Index

• func ContextWithTraceID(parent context.Context, ID string) context.Context
• func ContextWithTraceIDGenerator(parent context.Context, generator func() string) context.Context
• func ContextWithTracing(parent context.Context, t Traceable) context.Context
• func NewDebugLogger() *slog.Logger
• func NewTracingHandler(h slog.Handler) slog.Handler
• func Run(ctx context.Context, withOptions ...Option) (err error)
• func TraceIDFromContext(ctx context.Context) string
• type ContextFactory
• type Option
  • func WithAddress(host string, port uint32) Option
  • func WithContextFactory(f ContextFactory) Option
  • func WithDebugOptions() Option
  • func WithDefaultOptions() Option
  • func WithDefaultTraceIDGenerator() Option
  • func WithFirstSystemDSocketActivationSocket() Option
  • func WithHandler(h http.Handler) Option
  • func WithIdleTimeout(t time.Duration) Option
  • func WithListener(l net.Listener) Option
  • func WithLogger(logger *slog.Logger) Option
  • func WithMaxHeaderBytes(m int) Option
  • func WithOakHandler(h oakhttp.Handler, eh oakhttp.ErrorHandler) Option
  • func WithReadHeaderTimeout(t time.Duration) Option
  • func WithReadTimeout(t time.Duration) Option
  • func WithTLS(certificateFile, keyFile string) Option
  • func WithTraceIDGenerator(generator func() string) Option
  • func WithWriteTimeout(t time.Duration) Option
• type Traceable

Functions

func ContextWithTraceID

func ContextWithTraceID(parent context.Context, ID string) context.Context

func ContextWithTraceIDGenerator

func ContextWithTraceIDGenerator(parent context.Context, generator func() string) context.Context

func ContextWithTracing

func ContextWithTracing(parent context.Context, t Traceable) context.Context

func NewDebugLogger

func NewDebugLogger() *slog.Logger

func NewTracingHandler

func NewTracingHandler(h slog.Handler) slog.Handler

func Run

func Run(ctx context.Context, withOptions ...Option) (err error)

func TraceIDFromContext

func TraceIDFromContext(ctx context.Context) string

Types

type ContextFactory

type ContextFactory func(net.Listener) context.Context

type Option

type Option func(*options) error

func WithAddress

func WithAddress(host string, port uint32) Option

func WithContextFactory

func WithContextFactory(f ContextFactory) Option

func WithDebugOptions

func WithDebugOptions() Option

func WithDefaultOptions

func WithDefaultOptions() Option

func WithDefaultTraceIDGenerator

func WithDefaultTraceIDGenerator() Option

func WithFirstSystemDSocketActivationSocket

func WithFirstSystemDSocketActivationSocket() Option

WithSystemDSocketActivationPort binds the server to a listener specified by systemd configuration. This will preserve TCP connections during service restarts.

// /lib/systemd/system/myapp.socket
[Socket]
ListenStream = 80
#ListenStream = 443
BindIPv6Only = both
Service      = myapp.service

[Install]
WantedBy = sockets.target

// myapp.service
[Unit]
Description = myapp
After       = network.target

[Service]
Type = simple

ExecStart = /bin/myapp
ExecStop  = /bin/kill $MAINPID
KillMode  = none

[Install]
WantedBy = multi-user.target

See: https://bunrouter.uptrace.dev/guide/go-zero-downtime-restarts.html

sudo systemctl start myapp.socket sudo systemctl status myapp.socket sudo systemctl restart myapp.socket

func WithHandler

func WithHandler(h http.Handler) Option

func WithIdleTimeout

func WithIdleTimeout(t time.Duration) Option

func WithListener

func WithListener(l net.Listener) Option

func WithLogger

func WithLogger(logger *slog.Logger) Option

func WithMaxHeaderBytes

func WithMaxHeaderBytes(m int) Option

func WithOakHandler

func WithOakHandler(h oakhttp.Handler, eh oakhttp.ErrorHandler) Option

func WithReadHeaderTimeout

func WithReadHeaderTimeout(t time.Duration) Option

func WithReadTimeout

func WithReadTimeout(t time.Duration) Option

func WithTLS

func WithTLS(certificateFile, keyFile string) Option

func WithTraceIDGenerator

func WithTraceIDGenerator(generator func() string) Option

func WithWriteTimeout

func WithWriteTimeout(t time.Duration) Option

type Traceable

type Traceable interface {
	GetTraceID() string
}