sundial

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 1, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

README

Sundial

简体中文

Sundial is a lightweight, extensible, type-safe configuration SDK for Go with in-memory reads, persistent writes, and live updates.

Why Sundial

  • Type-safe access — applications read their own configuration struct instead of string paths and any values.
  • Fast reads — Get reads only from an in-memory snapshot.
  • Persistent writes — Put conditionally saves one complete typed configuration document.
  • Live updates — automatic reload keeps memory synchronized with external changes.
  • Extensible storage and formats — storage sources implement Provider; JSON works by default and other formats use codecs.

One Sundial instance manages one complete configuration document.

Installation

go get github.com/sundayfun/sundial

Quick start

Define the configuration owned by the application:

type Config struct {
	Server struct {
		Host string `json:"host"`
		Port int    `json:"port"`
	} `json:"server"`
	Debug bool `json:"debug"`
}

The following example uses S3:

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

configStore, err := s3provider.New[Config](ctx, &s3provider.Config{
	Region: "us-east-1",
	Bucket: "my-config-bucket",
	Key:    "production/app.json",
})
if err != nil {
	log.Fatal(err)
}
Read

Get returns a detached Entry from the current in-memory snapshot:

entry, err := configStore.Get()
if err != nil {
	log.Fatal(err)
}

fmt.Println(entry.Value.Server.Port)
Write

Modify the value and pass the same Entry back for a conditional write:

entry.Value.Server.Port = 9090
if err := configStore.Put(ctx, entry); err != nil {
	if sundial.IsConflict(err) {
		// Reload, reapply the change, and retry if appropriate.
		log.Print("configuration changed before it could be saved")
		return
	}
	log.Fatal(err)
}

Put uses the revision in entry.Metadata; a stale revision returns ErrConflict. It does not merge or retry automatically.

JSON is used by default. Other formats can be configured with WithCodec. Storage implementations live under provider/<source>.

See the runnable S3 example.

References

Behavior

  • A missing document causes New or Reload to return ErrNotFound.
  • An empty or whitespace-only document causes New, Put, or Reload to return a decode error.
  • A failed or conflicting Put leaves the current in-memory snapshot unchanged.
  • A failed reload keeps the last valid snapshot.
  • Canceling the context passed to New stops automatic reload.
  • Get is safe for concurrent use. Put calls are serialized per instance, and stale revisions return ErrConflict.

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotFound reports a missing configuration document.
	ErrNotFound = errors.New("sundial: not found")
	// ErrConflict reports that a write was based on a stale configuration revision.
	ErrConflict = errors.New("sundial: conflict")
	// ErrEmptyDocument reports an empty configuration document.
	ErrEmptyDocument = errors.New("sundial: empty configuration document")
)

Functions

func IsConflict

func IsConflict(err error) bool

func IsNotFound

func IsNotFound(err error) bool

Types

type Entry

type Entry[T any] struct {
	Value    T
	Metadata Metadata
}

Entry pairs a detached configuration value with the Provider metadata from the same in-memory snapshot.

type Metadata

type Metadata struct {
	Revision string
}

Metadata describes the Provider state paired with a configuration document.

type Option

type Option func(*options)

Option configures a Sundial instance.

func WithCodec

func WithCodec(value codec.Codec) Option

WithCodec configures the document codec. JSON is used by default.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger configures structured debug and automatic reload error logging.

func WithOnChange

func WithOnChange(callback func()) Option

WithOnChange sets the callback run after a changed configuration is published.

func WithOnError

func WithOnError(callback func(error)) Option

WithOnError sets the automatic reload error callback.

type Provider

type Provider interface {
	// Get returns the current document and its revision from the same logical
	// read. A missing document returns ErrNotFound and zero Metadata.
	Get(ctx context.Context) ([]byte, Metadata, error)
	// Put writes the document without checking the current revision.
	Put(ctx context.Context, data []byte) (Metadata, error)
	// PutIfRevision atomically replaces an existing document only when the non-empty
	// expectedMetadata.Revision matches the current revision. It returns the
	// metadata paired with the saved document; a mismatch returns ErrConflict.
	PutIfRevision(ctx context.Context, data []byte, expectedMetadata Metadata) (Metadata, error)
}

Provider reads and writes one complete configuration document.

type Sundial

type Sundial[T any] struct {
	// contains filtered or unexported fields
}

Sundial manages one typed configuration document and its in-memory state.

func New

func New[T any](ctx context.Context, provider Provider, opts ...Option) (*Sundial[T], error)

New loads the configuration and reloads it until ctx is canceled.

func (*Sundial[T]) Get

func (s *Sundial[T]) Get() (Entry[T], error)

Get returns the current detached Entry from memory.

func (*Sundial[T]) Put

func (s *Sundial[T]) Put(ctx context.Context, entry Entry[T]) error

Put saves entry when its metadata revision is current, then updates memory. A stale revision returns ErrConflict.

func (*Sundial[T]) Reload

func (s *Sundial[T]) Reload(ctx context.Context) error

Reload replaces the in-memory state when the Provider content changed.

type Watcher

type Watcher interface {
	Watch(ctx context.Context, notify func() error) error
}

Watcher detects Provider changes. Watch must notify once after registration and stop when ctx is canceled. A notify error means the change was not applied.

Directories

Path Synopsis
Package codec defines configuration document encoding and decoding.
Package codec defines configuration document encoding and decoding.
json
Package json provides a JSON codec backed by the Go standard library.
Package json provides a JSON codec backed by the Go standard library.
yaml
Package yaml provides a YAML codec backed by go.yaml.in/yaml/v3.
Package yaml provides a YAML codec backed by go.yaml.in/yaml/v3.
examples
s3 command
provider
s3
Package s3 provides a Sundial Provider backed by one standard S3 object.
Package s3 provides a Sundial Provider backed by one standard S3 object.
testing
Package providertesting provides Provider implementations for Sundial tests.
Package providertesting provides Provider implementations for Sundial tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL