renders

package
v1.2.0 Latest Latest
Warning

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

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

Documentation

Overview

Package renders sends a campaign to the workspace's own rendering service, Litmus or Mailgun Inspect, for screenshots from real email clients (review 2026-10, CO-13). The composer's built-in previews are drawn in the browser from the compiled HTML and say so; this is the optional real thing.

The API key is the workspace's own, sealed at rest (secrets.Box) and never returned. Calls go through the address guard (netguard) like every call to a service outside the instance. Content leaves the instance only on purpose: a person asks for each render, it is audited, and the email is personalized for the synthetic sample contact, never a real one.

Index

Constants

View Source
const (
	Litmus         = "litmus"
	MailgunInspect = "mailgun_inspect"
)

Services a workspace can connect.

View Source
const (
	StatusPending = "pending"
	StatusDone    = "done"
	StatusFailed  = "failed"
)

Render and per-client states.

Variables

This section is empty.

Functions

func Register

func Register(h huma.API, s *Service)

Register adds the rendering service operations.

Types

type CampaignPath

type CampaignPath struct {
	api.WorkspaceInput
	CampaignID string `path:"campaignId" format:"uuid"`
}

CampaignPath is the {workspace}/{campaignId} part of render operations (exported: huma reads path parameters of embedded structs only when they're exported).

type CampaignRenderInput

type CampaignRenderInput struct {
	Clients []string `` /* 131-byte string literal not displayed */
	Variant string   `json:"variant,omitempty" enum:"A,B,C" doc:"The A/B variant to render (A by default)"`
}

CampaignRenderInput asks for a render of the saved campaign.

type Content

type Content interface {
	// SampleRender is the campaign's saved content (one A/B variant)
	// personalized for the synthetic sample contact, so no contact's data
	// leaves the instance.
	SampleRender(ctx context.Context, ws *store.Workspace, p *authz.Principal, campaignID uuid.UUID, variant string) (Email, error)
	// CampaignName is the campaign's name, or a 404 problem when the
	// workspace has no such campaign.
	CampaignName(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (string, error)
}

Content gives the email to render (internal/campaigns, wired in internal/app).

type Email

type Email struct {
	Subject string
	HTML    string
	Version int
	// Name is the campaign's, for the audit log.
	Name string
}

Email is what a service renders: a saved version of the campaign as the sample contact gets it.

type Render

type Render struct {
	ID          string         `json:"id"`
	Version     int            `json:"version" doc:"The saved version rendered"`
	Variant     string         `json:"variant" enum:"A,B,C"`
	Service     string         `json:"service" enum:"litmus,mailgun_inspect"`
	Status      string         `json:"status" enum:"pending,done,failed"`
	Results     []RenderResult `json:"results"`
	Error       string         `json:"error,omitempty"`
	RequestedBy string         `json:"requestedBy"`
	RequestedAt time.Time      `json:"requestedAt"`
	CompletedAt *time.Time     `json:"completedAt,omitempty"`
}

Render is one request to the service and what it returned.

type RenderClient

type RenderClient struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	// Default marks the clients picked when nobody chooses: Gmail, Outlook,
	// Apple Mail, iPhone, Android, Yahoo, when the account has them.
	Default bool `json:"default"`
}

RenderClient is an email client a service renders in.

type RenderList

type RenderList struct {
	Items []Render `json:"items"`
}

RenderList is a campaign's latest renders, newest first.

type RenderResult

type RenderResult struct {
	Client   string `json:"client"`
	Name     string `json:"name"`
	Status   string `json:"status" enum:"pending,done,failed"`
	ImageURL string `json:"imageUrl,omitempty" doc:"The full screenshot, hosted by the service"`
	ThumbURL string `json:"thumbUrl,omitempty"`
}

RenderResult is one client's screenshot.

type RenderingConnectInput

type RenderingConnectInput struct {
	Service string `json:"service" enum:"litmus,mailgun_inspect"`
	APIKey  string `json:"apiKey" minLength:"8" maxLength:"256" doc:"Write-only: sealed at rest and never returned"`
	Region  string `json:"region,omitempty" enum:"us,eu" doc:"Mailgun Inspect: the account's region (us by default)"`
}

RenderingConnectInput connects (or replaces) the workspace's service.

type RenderingService

type RenderingService struct {
	Connected bool   `json:"connected"`
	Service   string `json:"service,omitempty" enum:"litmus,mailgun_inspect"`
	Region    string `json:"region,omitempty" enum:"us,eu" doc:"Mailgun Inspect: the account's region"`
	// KeyHint is the key's last four characters; the key itself is never returned.
	KeyHint     string         `json:"keyHint,omitempty"`
	Status      string         `json:"status,omitempty" enum:"connected,failing" doc:"failing: the last call was refused or failed (lastError says why)"`
	LastError   string         `json:"lastError,omitempty"`
	ConnectedBy string         `json:"connectedBy,omitempty"`
	ConnectedAt *time.Time     `json:"connectedAt,omitempty"`
	CheckedAt   *time.Time     `json:"checkedAt,omitempty"`
	Clients     []RenderClient `json:"clients" doc:"The email clients the account can render, as the service last listed them"`
}

RenderingService is the workspace's connection, without its key.

type Service

type Service struct {
	Pool    *pgxpool.Pool
	Q       *store.Queries
	Audit   *audit.Logger
	Box     *secrets.Box
	Content Content
	// HTTP calls the services (a netguard client in the app).
	HTTP *http.Client
	Now  func() time.Time
}

Service is the rendering service domain.

func (*Service) Connect

Connect tests a key with the service, then keeps it (sealed).

func (*Service) Disconnect

func (s *Service) Disconnect(ctx context.Context, ws *store.Workspace) error

Disconnect forgets the service and its key. Renders already made stay.

func (*Service) Get

Get returns the workspace's connection (Connected false when none).

func (*Service) List

func (s *Service) List(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (RenderList, error)

List returns the campaign's latest renders, asking the service about running ones (at most every few seconds, whoever is watching).

func (*Service) Start

func (s *Service) Start(ctx context.Context, ws *store.Workspace, p *authz.Principal, campaignID uuid.UUID, in CampaignRenderInput) (Render, error)

Start sends the campaign's saved content to the service for the clients.

func (*Service) Test

Test asks the service again with the stored key and records the outcome.

Jump to

Keyboard shortcuts

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