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]) Close()
- func (s *Client[T]) Get() T
- func (s *Client[T]) GetEntry() Entry[T]
- 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]) Reload(ctx context.Context) error
- func (s *Client[T]) RestoreRevision(ctx context.Context, targetRevisionID string, currentRevisionID string) (Entry[T], error)
- func (s *Client[T]) Update(ctx context.Context, modify func(*T) error) (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 ( // ErrClosed reports an operation on a closed Client. ErrClosed = errors.New("sundial: client closed") // 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") // ErrReadOnly reports a write rejected by a read-only Provider. ErrReadOnly = errors.New("sundial: read-only provider") // 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 or Close is called. Get and GetEntry return shared read-only values; use Update to publish changes.
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 := context.Background()
// 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)
}
defer client.Close()
fmt.Println(client.Get().Port)
}
Output: 8080
func (*Client[T]) Close ¶ added in v0.0.6
func (s *Client[T]) Close()
Close stops automatic reloads and waits for the watcher to exit. Snapshot reads remain available; writes, reloads and history operations are rejected. Repeated and concurrent calls are safe. Operations already in progress may complete. The parent context and provider are unaffected. A slow shutdown logs a warning after five seconds and continues waiting. Do not call Close synchronously from Watch or reload callbacks: it waits for that same watcher to return.
func (*Client[T]) Get ¶ added in v0.0.2
func (s *Client[T]) Get() T
Get returns the current shared read-only configuration without encoding or decoding. Callers must not modify its maps, slices, pointers or other referenced data. Use GetEntry when the configuration and its revision are needed together. After Close, Get logs ErrClosed and returns the latest retained snapshot.
func (*Client[T]) GetEntry ¶ added in v0.0.4
GetEntry returns the current configuration and its revision from one atomic read. Its Value follows the same shared read-only contract as Get. After Close, GetEntry logs ErrClosed and returns the latest retained snapshot.
func (*Client[T]) GetRevision ¶ added in v0.0.2
GetRevision returns a detached historical configuration value and its revision. It returns ErrClosed after Close.
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. It returns ErrClosed after Close.
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. Reload returns ErrClosed after Close.
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. The returned Entry is shared and read-only. RestoreRevision returns ErrClosed after Close.
func (*Client[T]) Update ¶ added in v0.0.3
Update decodes the current snapshot's source document into an independent draft, applies modify, and publishes it using that snapshot's revision. Local writes and reloads are serialized for the entire operation; storage still enforces revision CAS. If modify, encoding, decoding or publication fails, the accepted snapshot is preserved. The returned Entry is shared and read-only. modify must not call Update, Reload or RestoreRevision on this Client because they acquire the same lock. Update returns ErrClosed after Close.
Example ¶
package main
import (
"context"
"fmt"
"github.com/sundayfun/sundial"
providertesting "github.com/sundayfun/sundial/provider/testing"
)
func main() {
type Config struct {
Labels map[string]string `json:"labels"`
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
provider := providertesting.New([]byte(`{"labels":{"region":"east"}}`))
client, err := sundial.New[Config](ctx, provider)
if err != nil {
panic(err)
}
// Edit an independent draft without first calling Get.
saved, err := client.Update(ctx, func(config *Config) error {
config.Labels["region"] = "west"
return nil
})
if err != nil {
panic(err)
}
fmt.Println(saved.Value.Labels["region"])
fmt.Println(client.Get().Labels["region"])
}
Output: west west
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)
}
staleClient, err := sundial.New[Config](ctx, provider)
if err != nil {
panic(err)
}
// Stop automatic reloads so the second client keeps the original snapshot.
cancel()
writeCtx := context.Background()
if _, err = client.Update(writeCtx, func(config *Config) error {
config.Port = 9090
return nil
}); err != nil {
panic(err)
}
// A write based on the second client's stale snapshot cannot overwrite it.
_, err = staleClient.Update(writeCtx, func(config *Config) error {
config.Port = 7070
return nil
})
fmt.Println(sundial.IsConflict(err))
fmt.Println(client.Get().Port)
}
Output: true 9090
Example (Port) ¶
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 := client.GetEntry()
saved, err := client.Update(ctx, func(config *Config) error {
config.Port = 9090
return nil
})
if err != nil {
panic(err)
}
current := client.GetEntry()
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
type Entry ¶
type Entry[T any] struct { // Value is shared and read-only when returned by GetEntry, Update, // RestoreRevision or OnChange. Value T // Revision describes the immutable revision paired with Value. Revision Revision }
Entry pairs a 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. The callback receives a shared read-only Entry and must not modify its references. It runs on the watcher goroutine and must not call Client.Close synchronously.
func WithOnError ¶
WithOnError sets the automatic reload error callback. It runs on the watcher goroutine and must not call Client.Close synchronously.
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. |
|
static
Package static provides a read-only Sundial Provider for a fixed document.
|
Package static provides a read-only Sundial Provider for a fixed document. |
|
testing
Package providertesting provides Provider implementations for Sundial tests.
|
Package providertesting provides Provider implementations for Sundial tests. |
