channels

package
v0.0.13 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package channels holds the installation's channels: their configuration (exactly one provider each), the runtime of each (pool, rate, timeout) and which channel a kind uses by default.

Index

Constants

View Source
const (
	ProviderSMTP    = "smtp"
	ProviderFCM     = "fcm"
	ProviderWebPush = "webpush"
	ProviderLog     = "log"
)

Providers of the built-in kinds.

View Source
const (
	KindMail    = "mail"
	KindPush    = "push"
	KindWebPush = "webpush"
)

Built-in kinds of delivery.

Variables

View Source
var (
	ErrUnknown   = errors.New("channels: no such channel")
	ErrWrongKind = errors.New("channels: the channel delivers another kind")
	ErrNoDefault = errors.New("channels: name a channel: the kind has several and no default")
	ErrProvider  = errors.New("channels: no such provider")
)

Errors of picking a channel; final for a delivery.

View Source
var (
	ErrNoChannels = errors.New("channels: at least one channel is required")
	ErrConfig     = errors.New("channels: invalid channel")
)

Errors of the configuration.

Functions

This section is empty.

Types

type Channel

type Channel struct {
	Name string
	// Kind: mail, push or a provider's kind.
	Kind string
	// Provider: smtp, fcm, webpush, log, or the extension's name.
	Provider string
	Spec     Spec

	Mail      *smtp.Sender
	Push      *fcm.Client
	WebPush   *webpush.Client
	Extension *Extension
	// Settings of an extension channel as JSON (settings and secrets).
	Settings []byte
	// contains filtered or unexported fields
}

Channel at run time.

func (*Channel) Acquire

func (c *Channel) Acquire(ctx context.Context) (func(), error)

Acquire a delivery slot within the channel's pool and rate; release it when done.

func (*Channel) Timeout

func (c *Channel) Timeout() time.Duration

Timeout of one delivery.

type Channels

type Channels struct {
	deps.Component
	// contains filtered or unexported fields
}

Channels is the component: every channel and the defaults by kind.

func New

func New(parent deps.Scope, cfg Config, opts Options) (*Channels, error)

New builds the channels of cfg (validated by Open).

func (*Channels) All

func (c *Channels) All() map[string]*Channel

All channels by name.

func (*Channels) Get

func (c *Channels) Get(name string) (*Channel, bool)

Get a channel by name.

func (*Channels) IsDefault

func (c *Channels) IsDefault(ch *Channel) bool

IsDefault reports whether ch is its kind's default (named or the only one).

func (*Channels) Pick

func (c *Channels) Pick(kind, name string) (*Channel, error)

Pick is the channel a delivery of kind uses: the one named, else the kind's default, else the kind's only channel.

type Config

type Config map[string]Spec

Config is the channels by name.

func (Config) Names

func (c Config) Names() []string

Names of the channels, sorted.

func (Config) Validate

func (c Config) Validate() error

Validate every channel.

type Extension

type Extension struct {
	Name       string
	Provider   provider.Provider
	Descriptor provider.Descriptor
	// Plugin: it runs as its own service; false: compiled in.
	Plugin bool
	// Health of a plugin: reachable, serving, same contract; nil for a
	// compiled-in provider.
	Health func(ctx context.Context) error
}

Extension is a provider courier loaded (a plugin or a compiled-in one).

type Log

type Log struct {
	Kind string `json:"kind" schemapb:"description=The kind it stands in for: mail, push, webpush or a provider's"`
}

Log stands in for a kind: mail, push or a provider's.

type Options

type Options struct {
	// Extensions by name: plugins and compiled-in providers.
	Extensions map[string]*Extension
	// Defaults: the channel of a kind when a message names none.
	Defaults map[string]string
	// TokenSource authorizes every FCM channel instead of its credentials.
	TokenSource oauth2.TokenSource
	// WebPushClient posts to push services (tests); nil: the default.
	WebPushClient *http.Client
}

Options of New.

type Plugin

type Plugin struct {
	// Address: unix:///path or host:port.
	Address string `json:"address" schemapb:"description=unix:///path or host:port of the plugin"`
	// TLS of the connection; off: plaintext (a sidecar, a unix socket).
	TLS config.TLS `json:"tls"`
	// StartupTimeout: how long courier waits at startup for the plugin to
	// answer Describe.
	StartupTimeout time.Duration `json:"startup_timeout" schemapb:"default=30s"`
}

Plugin is a provider running somewhere courier can dial: how and where it runs is the deployment's concern. Courier waits for it at startup, probes its gRPC health as part of its own readiness, and keeps the connection alive.

func (Plugin) Validate

func (p Plugin) Validate() error

Validate a plugin.

type Provider

type Provider struct {
	Name string `json:"name" schemapb:"description=The plugin or compiled-in provider"`
	// Settings and Secrets are the channel's settings for the provider,
	// merged; secrets are masked wherever the configuration is shown.
	Settings map[string]string        `json:"settings,omitempty"`
	Secrets  map[string]config.Secret `json:"secrets,omitempty"`
}

Provider names an extension provider and its channel settings.

type Spec

type Spec struct {
	SMTP    *smtp.Config    `json:"smtp,omitempty"    schemapb:"description=Mail through an SMTP relay"`
	FCM     *fcm.Config     `json:"fcm,omitempty"     schemapb:"description=Push through Firebase Cloud Messaging"`
	WebPush *webpush.Config `json:"webpush,omitempty" schemapb:"description=Web Push to browsers (VAPID)"`
	Log     *Log            `json:"log,omitempty"     schemapb:"description=Deliveries go to the service log"`
	// Provider is a plugin or a compiled-in provider, by name.
	Provider *Provider `json:"provider,omitempty" schemapb:"description=A plugin or a compiled-in provider"`

	// Pool bounds the deliveries in flight on the channel.
	Pool int64 `json:"pool" schemapb:"default=8;gte=1;lte=1024"`
	// RatePerMinute bounds deliveries per minute; 0: unbounded.
	RatePerMinute int64         `json:"rate_per_minute" schemapb:"default=0;gte=0"`
	Timeout       time.Duration `json:"timeout"         schemapb:"default=30s"`
}

Spec is one channel: exactly one of smtp, fcm, webpush, log or provider.

func (Spec) Validate

func (c Spec) Validate() error

Validate checks exactly one provider and its own rules.

Jump to

Keyboard shortcuts

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