Documentation
¶
Overview ¶
Package sundial provides a type-safe client for managing one complete configuration document with in-memory reads, conditional persistent writes, and automatic reloads.
Index ¶
- Constants
- Variables
- func IsConflict(err error) bool
- func IsInvalidRevision(err error) bool
- func IsNotFound(err error) bool
- func IsUnsupported(err error) bool
- type Client
- func (s *Client[T]) Get() (Entry[T], error)
- func (s *Client[T]) GetRevision(ctx context.Context, revisionID string) (T, Revision, error)
- func (s *Client[T]) ListRevisions(ctx context.Context, opts ListRevisionsOptions) ([]Revision, error)
- func (s *Client[T]) Put(ctx context.Context, entry Entry[T]) (Entry[T], error)
- func (s *Client[T]) Reload(ctx context.Context) error
- func (s *Client[T]) RestoreRevision(ctx context.Context, targetRevisionID string, currentRevisionID string) (Entry[T], error)
- type Entry
- type ListRevisionsOptions
- type Option
- type Provider
- type Revision
- type RevisionManager
- type Watcher
Examples ¶
Constants ¶
const DefaultListRevisionsLimit = 256
DefaultListRevisionsLimit bounds history traversal when no positive limit is provided.
Variables ¶
var ( // ErrNotFound reports a missing configuration document. ErrNotFound = errors.New("sundial: not found") // ErrConflict reports a failed write condition, including an empty or stale revision ID. ErrConflict = errors.New("sundial: conflict") // ErrEmptyDocument reports an empty configuration document. ErrEmptyDocument = errors.New("sundial: empty configuration document") // ErrUnsupported reports that a Provider does not implement an optional capability. ErrUnsupported = errors.New("sundial: unsupported operation") // ErrInvalidRevision reports corrupt immutable revision data. ErrInvalidRevision = errors.New("sundial: invalid revision") )
Functions ¶
func IsConflict ¶
IsConflict reports whether err indicates a failed write condition.
func IsInvalidRevision ¶ added in v0.0.2
IsInvalidRevision reports whether err indicates corrupt immutable revision data.
func IsNotFound ¶
IsNotFound reports whether err indicates a missing configuration document.
func IsUnsupported ¶ added in v0.0.2
IsUnsupported reports whether err indicates an unsupported Provider capability.
Types ¶
type Client ¶ added in v0.0.2
type Client[T any] struct { // contains filtered or unexported fields }
Client manages one typed configuration document and its in-memory state.
func New ¶
New loads an existing configuration and reloads it until ctx is canceled.
Example ¶
package main
import (
"context"
"fmt"
"github.com/sundayfun/sundial"
providertesting "github.com/sundayfun/sundial/provider/testing"
)
func main() {
type Config struct {
Port int `json:"port"`
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel() // Stop automatic reloads when the client is no longer needed.
// Use an in-memory test provider with an existing JSON document.
provider := providertesting.New([]byte(`{"port":8080}`))
client, err := sundial.New[Config](ctx, provider)
if err != nil {
panic(err)
}
entry, err := client.Get()
if err != nil {
panic(err)
}
fmt.Println(entry.Value.Port)
}
Output: 8080
func (*Client[T]) GetRevision ¶ added in v0.0.2
GetRevision returns a detached historical configuration value and its revision.
func (*Client[T]) ListRevisions ¶ added in v0.0.2
func (s *Client[T]) ListRevisions( ctx context.Context, opts ListRevisionsOptions, ) ([]Revision, error)
ListRevisions returns immutable revisions in newest-first order.
func (*Client[T]) Put ¶ added in v0.0.2
Put saves entry when its revision ID is current, then updates memory. It returns the codec-decoded saved Entry with its new revision. A stale or empty revision ID returns ErrConflict.
Example ¶
package main
import (
"context"
"fmt"
"github.com/sundayfun/sundial"
providertesting "github.com/sundayfun/sundial/provider/testing"
)
func main() {
type Config struct {
Port int `json:"port"`
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
provider := providertesting.New([]byte(`{"port":8080}`))
client, err := sundial.New[Config](ctx, provider)
if err != nil {
panic(err)
}
entry, err := client.Get()
if err != nil {
panic(err)
}
// Keep the observed revision while changing the complete document's value.
entry.Value.Port = 9090
saved, err := client.Put(ctx, entry)
if err != nil {
panic(err)
}
current, err := client.Get()
if err != nil {
panic(err)
}
fmt.Println(saved.Value.Port)
fmt.Println(saved.Revision.ID != entry.Revision.ID)
fmt.Println(current.Revision.ID == saved.Revision.ID)
}
Output: 9090 true true
Example (Conflict) ¶
package main
import (
"context"
"fmt"
"github.com/sundayfun/sundial"
providertesting "github.com/sundayfun/sundial/provider/testing"
)
func main() {
type Config struct {
Port int `json:"port"`
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
provider := providertesting.New([]byte(`{"port":8080}`))
client, err := sundial.New[Config](ctx, provider)
if err != nil {
panic(err)
}
entry, err := client.Get()
if err != nil {
panic(err)
}
stale := entry
entry.Value.Port = 9090
if _, err = client.Put(ctx, entry); err != nil {
panic(err)
}
// A second write based on the old revision must not overwrite the first.
stale.Value.Port = 7070
_, err = client.Put(ctx, stale)
fmt.Println(sundial.IsConflict(err))
current, err := client.Get()
if err != nil {
panic(err)
}
fmt.Println(current.Value.Port)
}
Output: true 9090
func (*Client[T]) Reload ¶ added in v0.0.2
Reload updates the in-memory content and revision from the Provider. On error, the previous snapshot is preserved.
func (*Client[T]) RestoreRevision ¶ added in v0.0.2
func (s *Client[T]) RestoreRevision( ctx context.Context, targetRevisionID string, currentRevisionID string, ) (Entry[T], error)
RestoreRevision publishes targetRevisionID as a new revision if currentRevisionID still matches storage. currentRevisionID is the revision observed by the caller; an empty or stale ID returns ErrConflict. It decodes the historical content before writing and preserves its original bytes.
type Entry ¶
type Entry[T any] struct { // Value is a detached copy of the configuration document. Value T // Revision describes the immutable revision paired with Value. Revision Revision }
Entry pairs a detached configuration value with its revision.
type ListRevisionsOptions ¶ added in v0.0.2
type ListRevisionsOptions struct {
// Limit caps the number of newest-first results. Non-positive uses the default limit.
Limit int
// Offset skips this many newest revisions. Non-positive starts from the newest.
Offset int
}
ListRevisionsOptions controls history queries.
type Option ¶
type Option[T any] func(*options[T])
Option configures a Client.
func WithLogger ¶
WithLogger configures structured diagnostic logging.
func WithOnChange ¶
WithOnChange sets the callback run after automatic reload publishes a changed configuration.
func WithOnError ¶
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.
Get(ctx context.Context) ([]byte, Revision, error)
// Put writes the document without requiring a caller-supplied revision.
// Providers may use internal concurrency checks and return ErrConflict
// when concurrent writes prevent publication.
Put(ctx context.Context, data []byte) (Revision, error)
// PutIfRevision atomically replaces an existing document if currentRevisionID,
// the revision observed by the caller, still matches storage. It returns the
// saved revision; an empty or stale ID returns ErrConflict.
PutIfRevision(ctx context.Context, data []byte, currentRevisionID string) (Revision, error)
}
Provider reads and writes one complete configuration document.
type Revision ¶ added in v0.0.2
type Revision struct {
// ID uniquely identifies the immutable revision.
ID string
// ParentID identifies the previously active revision.
ParentID string
// CreatedAt is the revision creation time.
CreatedAt time.Time
}
Revision describes one immutable configuration revision.
type RevisionManager ¶ added in v0.0.2
type RevisionManager interface {
// GetRevision returns an immutable revision's content and descriptor.
GetRevision(ctx context.Context, revisionID string) ([]byte, Revision, error)
// ListRevisions returns immutable revisions in newest-first order.
ListRevisions(ctx context.Context, opts ListRevisionsOptions) ([]Revision, error)
}
RevisionManager provides optional configuration history operations.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
sundial
command
Command sundial manages versioned configuration documents.
|
Command sundial manages versioned configuration documents. |
|
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 versioned Sundial Provider backed by standard S3 objects.
|
Package s3 provides a versioned Sundial Provider backed by standard S3 objects. |
|
testing
Package providertesting provides Provider implementations for Sundial tests.
|
Package providertesting provides Provider implementations for Sundial tests. |
