simulator

package
v1.3.1 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: AGPL-3.0 Imports: 14 Imported by: 0

Documentation

Overview

Package simulator is the demo transport: a sending provider that touches no network. It accepts messages like the provider it stands in for (SES, Postal, Postmark, SMTP), answers with that provider's codes, and plans the delivery and engagement events the real one would report over time, at the per-mailbox-provider rates of the design boards. Scenarios reproduce the guarded-sending states: "outlook-complaints" raises complaints among never-engaged Outlook recipients until the auto-pause trips, and "postal-outage" makes a Postal server refuse connections 14 minutes into the send.

The sending engine selects it only for providers whose providers.config holds "demo": true (set by the demo seeder; the API never sets it). It is not in the public adapter catalog, so it can't be connected.

Index

Constants

View Source
const (
	ScenarioNormal            = "normal"
	ScenarioOutlookComplaints = "outlook-complaints"
	ScenarioPostalOutage      = "postal-outage"
	ScenarioSteady            = "steady"
)

Scenarios. Steady is normal without the provider throttling a call now and then: a send's timing is the engine's rules alone, as an estimate plays them.

View Source
const (
	OutageAfter = 14 * time.Minute
	OutageLasts = 25 * time.Minute
)

Outage timing of the postal-outage scenario, measured from the send's start.

View Source
const (
	TagTier    = "rc_sim_tier"
	TagEngaged = "rc_sim_engaged"
	TagSource  = "rc_sim_source"
	TagMailbox = "rc_sim_mailbox"
)

Hint tags the engine adds to messages for the simulator only (never sent to a real provider): the recipient's engagement tier, whether they ever opened, how they joined and the mailbox provider.

View Source
const Adapter = "simulator"

Adapter is the transport's key.

Variables

Scenarios lists the valid scenario names.

Functions

func Descriptor

func Descriptor() providers.Descriptor

Descriptor describes the simulator for tests that need it registered.

func New

New builds the simulator from a provider's configuration.

func Sign

func Sign(secret string, body []byte) string

Sign signs a webhook body (contract tests).

func WithNow

func WithNow(ctx context.Context, t time.Time) context.Context

WithNow carries the sending engine's clock to Send, so a send driven on a virtual clock (tests, a fast-forwarded demo send) sees scenario timing on that clock.

Types

type Event

type Event struct {
	// Kind: delivered, deferred, hard_bounce, soft_bounce, complaint,
	// open, click.
	Kind string
	// After is the delay from acceptance.
	After        time.Duration
	OriginalType string
	Code         string
	Diagnostic   string
	BounceClass  string
	// Opens and clicks: who fetched the pixel or followed the link.
	UserAgent string
	IP        string
	// Link picks the clicked link (0–1, weighted towards the first links).
	Link float64
}

Event is something the simulated provider (or the recipient) will do after a message was accepted.

type Provider

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

Provider is the simulated transport.

func (*Provider) Adapter

func (p *Provider) Adapter() string

Adapter implements providers.Provider.

func (*Provider) Capabilities

func (p *Provider) Capabilities() providers.Capabilities

Capabilities implements providers.Provider.

func (*Provider) Outage

func (p *Provider) Outage(t time.Time) bool

Outage reports whether the scenario has the provider down at t.

func (*Provider) ParseWebhook

func (p *Provider) ParseWebhook(ctx context.Context, r *http.Request, body []byte) ([]providers.Event, error)

ParseWebhook implements providers.Provider. The simulator never receives webhooks in the app (its events are applied directly); the format exists so it passes the shared contract suite: a JSON array of events signed with HMAC-SHA256 of the body in X-Simulator-Signature.

func (*Provider) Plan

func (p *Provider) Plan(m providers.Message) []Event

Plan returns what will happen to an accepted message.

func (*Provider) Send

func (p *Provider) Send(ctx context.Context, msgs []providers.Message) ([]providers.SendResult, error)

Send implements providers.Provider: every message is accepted unless the scenario has the provider down, or (rarely) the provider throttles.

func (*Provider) SendWithExtras

func (p *Provider) SendWithExtras(ctx context.Context, msgs []providers.Message, _ []providers.MessageExtras) ([]providers.SendResult, error)

SendWithExtras implements providers.ExtrasSender: the demo transport accepts copies and attachments like the adapter it stands in for.

func (*Provider) WithClock

func (p *Provider) WithClock(now func() time.Time) *Provider

WithClock replaces the clock (tests and fast-forwarded demo sends).

type Settings

type Settings struct {
	Demo bool `json:"demo"`
	// Mimic is the adapter whose answers the simulator gives.
	Mimic    string `json:"mimic"`
	Scenario string `json:"scenario"`
	// Started is when the campaign send started (scenario timing).
	Started time.Time `json:"started"`
	// Host names the server in error messages ("mta.acme.io").
	Host string `json:"server_url"`
	IP   string `json:"ip"`
}

Settings are the simulator's options, read from the provider's config plus what the engine adds for one send.

Jump to

Keyboard shortcuts

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