Help us shape the future of Go! Take the 2026 Go Developer Survey

integrations

package
v0.3.5 Latest Latest
Warning

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

 Go to latest Published: Oct 27, 2026 License: AGPL-3.0 Imports: 31 Imported by: 0

Documentation

Overview

Package integrations is the use-case module for a Workspace's sending-provider Integrations: config validation, credential sealing, the default-per-channel rule and the redacted read view. /site and /api are thin adapters over it, so the two surfaces cannot diverge on how a credential is stored or what is refused.

Handlers hand in a *ent.Scoped and domain-typed input (not their DTOs) and get back the row or a domain error: validation.Error (a 422), ErrDefaultConflict (a 409), or ent's not-found for an unknown id.

Index

Constants

View Source 
const SecretMask = "********"

SecretMask is what a read shows in place of a secret param. Sending it back, or a blank, or nothing, leaves the stored secret as it is.

Variables

View Source 
var ErrDefaultConflict = validation.Refuse("a default provider already exists for this channel", "errors.integration_default_conflict")

ErrDefaultConflict means another default Integration already exists for the channel.

View Source 
var ErrNotFound = validation.Refuse("integrations: integration not found", "errors.integration_not_found")

ErrNotFound means there is no such Integration in this Workspace.

View Source 
var ErrOneInbox = validation.Refuse("a workspace has at most one Test inbox", "errors.integration_one_inbox")

ErrOneInbox means the Workspace already keeps a Test inbox: it has at most one (ADR 0058).

Functions

func IsConflict 

func IsConflict(err error) bool

IsConflict reports whether err is one of the refusals a handler answers with 409.

func ParamsOf 

func ParamsOf[M ~map[string]jx.Raw](raw M) (map[string]any, error)

ParamsOf turns the opaque params object of a request into Go values.

func RawOf 

func RawOf(values map[string]any) map[string]jx.Raw

RawOf renders params as the opaque object of a response.

Types

type ConfigInput 

type ConfigInput struct {
	SMTP  *SMTPConfig
	SES   *SESConfig
	Inbox *InboxConfig
}

ConfigInput carries exactly one provider's settings.

type CreateInput 

type CreateInput struct {
	Name         string
	Enabled      *bool
	IsDefault    bool
	MaxPerSecond Limit
	MaxPerDay    Limit
	Config       ConfigInput
	// Preset and Params are the inbound side (ADR 0037); Params without a Preset is refused.
	Preset *string
	Params map[string]any
}

CreateInput is a new Integration. Enabled defaults to true when nil.

type InboxConfig 

type InboxConfig struct{}

InboxConfig is the Test inbox's settings: it has none.

type Limit 

type Limit struct {
	Set   bool
	Value *int
}

Limit is a Send rate limit in a request: unset keeps the stored value (update) or means no limit (create); Value nil with Set true clears it.

func LimitOf 

func LimitOf[T ~int32](in interface {
	Get() (T, bool)
	IsSet() bool
}) Limit

LimitOf reads a Send rate limit from an optional-nullable request field (the generated OptNil types of either API): omitted is unset, null clears, a number sets.

type Module 

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

Module holds the shared collaborators; it is stateless otherwise.

func New 

func New(bus *events.Bus, cipher *secrets.Cipher, catalog *messaging.Catalog, quota QuotaEnqueuer, presets *preset.Registry, appURL string, opts ...Option) *Module

New builds the module. presets is the Instance's Preset registry and appURL the public origin the hook URLs are built from.

func (*Module) All 

func (m *Module) All(ctx context.Context, s *ent.Scoped, archived bool) ([]*ent.Integration, error)

All returns every kept Integration of the Workspace, or with archived every archived one, ascending by id.

func (*Module) Archive 

func (m *Module) Archive(ctx context.Context, s *ent.Scoped, id int64) error

Archive discards an Integration (ADR 0049), unless live work uses it: then it returns an *inuse.Error naming that work. A scheduled or sending Broadcast uses the Integration it names, and the default one when it names none; an active Automation that sends email uses the one it names, and the default one when it names none. A sent or failed Broadcast is history and does not block. An archived Integration gives up the default: its channel has none until another is picked. Archiving an archived Integration changes nothing. An unknown id is ErrNotFound.

func (*Module) ConfirmSubscription 

func (m *Module) ConfirmSubscription(ctx context.Context, url string) error

ConfirmSubscription performs a Preset's confirm action: it fetches the URL the provider asked to be fetched, through the SSRF-guarded client. The engine has already refused a URL the provider's own rules do not allow (SNS: an https SNS host only).

func (*Module) Create 

func (m *Module) Create(ctx context.Context, s *ent.Scoped, in CreateInput) (*ent.Integration, error)

Create validates and stores an Integration, sealing its credentials.

func (*Module) Get 

func (m *Module) Get(ctx context.Context, s *ent.Scoped, id int64) (*ent.Integration, error)

Get returns one Integration of the Workspace. An unknown id is ErrNotFound.

func (*Module) HookURL 

func (m *Module) HookURL(row *ent.Integration) string

HookURL is where the provider posts this Integration's callbacks.

func (*Module) List 

func (m *Module) List(ctx context.Context, s *ent.Scoped, p pagination.Params, archived bool) (pagination.Page[*ent.Integration], error)

List returns one page of the Workspace's Integrations, ascending by id: the kept ones, or with archived the archived ones.

func (*Module) Params 

func (m *Module) Params(row *ent.Integration) (preset.Params, error)

Params opens the stored params for the engine: a rotating secret is a list, the current value first.

func (*Module) Presets 

func (m *Module) Presets() *preset.Registry

Presets is the registry of Presets the Instance offers.

func (*Module) Redact 

func (m *Module) Redact(row *ent.Integration) (RedactedConfig, error)

Redact opens the stored config and returns it without secrets.

func (*Module) RegenerateKey 

func (m *Module) RegenerateKey(ctx context.Context, s *ent.Scoped, id int64) (*ent.Integration, error)

RegenerateKey gives the Integration a new hook key: the old hook URL stops working at once. The write is audited like any other edit of the Integration; the key itself never reaches the entry.

func (*Module) Unarchive 

func (m *Module) Unarchive(ctx context.Context, s *ent.Scoped, id int64) error

Unarchive brings an archived Integration back to the lists. It does not become the default again. Restoring an Integration that is not archived changes nothing. An unknown id is ErrNotFound.

func (*Module) Update 

func (m *Module) Update(ctx context.Context, s *ent.Scoped, id int64, in UpdateInput) (*ent.Integration, error)

Update applies a partial edit. An unknown id is ErrNotFound.

func (*Module) View 

func (m *Module) View(row *ent.Integration) (ParamsView, error)

View opens the stored params and returns them without a secret.

type Option 

type Option func(*Module)

Option tunes the module.

func WithSubscriptionConfirmer 

func WithSubscriptionConfirmer(f func(ctx context.Context, url string) error) Option

WithSubscriptionConfirmer replaces how a Preset's confirm action is performed: a GET through the SSRF-guarded client by default.

type ParamsView 

type ParamsView struct {
	Values          map[string]any
	SecretsRetiring []string
}

ParamsView is the read side of an Integration's params: the values as saved with each secret masked, and the secrets that are rotating.

type PresetChange 

type PresetChange struct {
	Set  bool
	Name *string
}

PresetChange is the Preset of a write: unset keeps the stored one, Name nil removes it.

func PresetOf 

func PresetOf(in interface {
	Get() (string, bool)
	IsSet() bool
}) PresetChange

PresetOf reads the Preset of an optional-nullable request field (the generated OptNilString of either API).

type QuotaEnqueuer 

type QuotaEnqueuer interface {
	EnqueueIntegrationQuotaRefresh(ctx context.Context, integrationID int64) error
}

QuotaEnqueuer schedules a read of one Integration's provider send quota (ADR 0023).

type RedactedConfig 

type RedactedConfig struct {
	SMTP  *RedactedSMTP
	SES   *RedactedSES
	Inbox *RedactedInbox
}

RedactedConfig is the read-side provider config: no password, no secret key.

type RedactedInbox 

type RedactedInbox struct{}

RedactedInbox is the Test inbox's config: it has no field.

type RedactedSES 

type RedactedSES struct {
	Region           string
	From             string
	FromName         string
	Endpoint         string
	AccessKeyIDLast4 string
}

type RedactedSMTP 

type RedactedSMTP struct {
	Host     string
	Port     int
	Username string
	From     string
	FromName string
}

type SESConfig 

type SESConfig struct {
	Region          string
	AccessKeyID     string
	SecretAccessKey string
	From            string
	FromName        string
	Endpoint        string
}

SMTPConfig and SESConfig are the write-side provider settings, secrets included.

type SMTPConfig 

type SMTPConfig struct {
	Host     string
	Port     int
	Username string
	Password string
	From     string
	FromName string
}

SMTPConfig and SESConfig are the write-side provider settings, secrets included.

type UpdateInput 

type UpdateInput struct {
	Name         *string
	Enabled      *bool
	IsDefault    *bool
	MaxPerSecond Limit
	MaxPerDay    Limit
	Config       *ConfigInput
	// Preset, Params and RetireSecrets edit the inbound side; see sealInbound.
	Preset        PresetChange
	Params        map[string]any
	RetireSecrets bool
}

UpdateInput is a partial edit; nil fields keep the stored value. A nil Config keeps the credentials; inside a supplied Config, blank secrets keep the stored secret.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.