CI Go Report Card GoDoc License: MIT

import "github.com/go-coldbrew/options"

• Constants
• func AddToLogFields(ctx context.Context, key string, value any) context.Context
• func AddToOptions(ctx context.Context, key string, value any) context.Context
• type Options
  • func FromContext(ctx context.Context) *Options
  • func LogFieldsFromContext(ctx context.Context) *Options
  • func (o *Options) Add(key string, value any)
  • func (o *Options) Del(key string)
  • func (o *Options) Delete(key any)
  • func (o *Options) Get(key string) (any, bool)
  • func (o *Options) Load(key any) (any, bool)
  • func (o *Options) Range(f func(key, value any) bool)
  • func (o *Options) RangeSlice(f func(key, value any) bool)
  • func (o *Options) Store(key, value any)
• type RequestContext
  • func RequestContextFromContext(ctx context.Context) *RequestContext
  • func (rc *RequestContext) LogFields() *Options
  • func (rc *RequestContext) Opts() *Options

SupportPackageIsVersion1 is a compile-time assertion constant. Downstream packages reference this to enforce version compatibility.

const SupportPackageIsVersion1 = true

func AddToLogFields(ctx context.Context, key string, value any) context.Context

AddToLogFields adds a key-value pair to the log fields stored in ctx. If ctx is nil, context.Background() is used.

func AddToOptions(ctx context.Context, key string, value any) context.Context

AddToOptions adds a key-value pair to the Options stored in ctx. If no Options exists in the context, a new one is created. Empty keys are silently ignored and do not allocate.

package main
import (
	"context"
	"fmt"
	"github.com/go-coldbrew/options"
)
func main() {
	ctx := context.Background()
	// Add request-scoped metadata to context
	ctx = options.AddToOptions(ctx, "tenant", "acme-corp")
	ctx = options.AddToOptions(ctx, "region", "us-west-2")
	// Retrieve values downstream
	opts := options.FromContext(ctx)
	if tenant, ok := opts.Get("tenant"); ok {
		fmt.Println("tenant:", tenant)
	}
	if region, ok := opts.Get("region"); ok {
		fmt.Println("region:", region)
	}
}

tenant: acme-corp
region: us-west-2

Options are request options passed from ColdBrew to server. Uses RWMutex + map instead of sync.Map since Options is per-request and never shared across goroutines.

type Options struct {
 // contains filtered or unexported fields
}

func FromContext(ctx context.Context) *Options

FromContext fetches options from provided context. If no options are found, it returns nil.

package main
import (
	"context"
	"fmt"
	"github.com/go-coldbrew/options"
)
func main() {
	ctx := context.Background()
	// Without any options set, FromContext returns nil
	opts := options.FromContext(ctx)
	fmt.Println("opts:", opts)
}

opts: <nil>

func LogFieldsFromContext(ctx context.Context) *Options

LogFieldsFromContext retrieves the log fields Options from context. Returns nil if not present.

func (o *Options) Add(key string, value any)

Add adds a key-value pair to Options. Empty keys are silently ignored.

func (o *Options) Del(key string)

Del deletes an option by key.

func (o *Options) Delete(key any)

Delete is a sync.Map-compatible alias for Del. Only string keys are supported; non-string keys are silently ignored.

func (o *Options) Get(key string) (any, bool)

Get retrieves an option value by key.

func (o *Options) Load(key any) (any, bool)

Load is a sync.Map-compatible alias for Get. Only string keys are supported; non-string keys return (nil, false).

func (o *Options) Range(f func(key, value any) bool)

Range calls f sequentially for each key and value. If f returns false, Range stops the iteration. The callback may safely call Add/Del on the same Options instance.

func (o *Options) RangeSlice(f func(key, value any) bool)

RangeSlice calls f sequentially for each key and value, using a slice snapshot. This is more efficient than Range for small maps and matches the iteration pattern used by LogFields.

func (o *Options) Store(key, value any)

Store is a sync.Map-compatible alias for Add. Only string keys are supported; non-string keys are silently ignored.

RequestContext holds both request-scoped options and log-scoped fields in a single context value, reducing context.WithValue allocations from 2 to 1. Both fields are eagerly initialized to avoid data races from concurrent lazy init.

type RequestContext struct {
 // contains filtered or unexported fields
}

func RequestContextFromContext(ctx context.Context) *RequestContext

RequestContextFromContext retrieves the RequestContext from ctx. Returns nil if not present.

func (rc *RequestContext) LogFields() *Options

LogFields returns the Options used for log fields.

func (rc *RequestContext) Opts() *Options

Opts returns the Options for request-scoped key-value pairs.

Generated by gomarkdoc