api

Documentation

Overview

Package api serves the HTTP API described in api/openapi.yaml.

Index

• func Allowance(st *store.Store, modules []ext.Module) func(ctx context.Context, tenantID int64, now time.Time) (bool, error)
• func CheckModules(mode string, modules []ext.Module) error
• func KeyModule(modules []ext.Module) (ext.KeyProvider, error)
• func LowerSeats(st *store.Store, modules []ext.Module) func(ctx context.Context, tenantID int64, now time.Time) error
• func NewHandler(o Options) http.Handler
• func PlanFeature(st *store.Store, modules []ext.Module, feature string) func(ctx context.Context, tenantID int64) bool
• type ModelSource
• type Options

Functions

func Allowance

func Allowance(st *store.Store, modules []ext.Module) func(ctx context.Context, tenantID int64, now time.Time) (bool, error)

Allowance is pipeline.Pipeline.Allowance for a build's modules: whether the tenant has used up the month's allowance of emails a model decides on keys the operator holds, at now. It is nil when the build sells no plans.

func CheckModules

func CheckModules(mode string, modules []ext.Module) error

CheckModules refuses a build whose modules, or mode (MAILRULES_MODE), the daemon cannot serve: a Webhook route that is not Public, a SignIn or SignOut that does not name one of its module's Public GET routes, a SignOut or DeleteIdentity without SignIn, more than one module with SignIn, and cloud mode with no module that signs people in; a Mailboxes with no Login, with a provider other than gmail or outlook, with gmail but no Google client ID (or Google without gmail, or an admin help page not on https), or whose Connect is not one of its module's signed-in GET routes, and more than one module with Mailboxes; a MailboxForm for a provider other than proton, or whose Path is not one of its module's signed-in POST routes under /api/, and two forms for one provider; a MailboxRemoved with neither Mailboxes nor MailboxForms; a Notifications with no Notify or no kind, or a kind other than webhook or slack, and more than one module with Notifications; a Drafts with no Write, and more than one module with Drafts; a Moves with no Moved or a negative Every, and more than one module with Moves; a Billing the daemon cannot serve (checkBilling), and more than one module with Billing; and a Keys the daemon cannot use (KeyModule). The daemon calls it before it serves anything.

func KeyModule

func KeyModule(modules []ext.Module) (ext.KeyProvider, error)

KeyModule is the key provider of the build's module that holds the keys (ext.Module.Keys), nil when none does. It refuses more than one, and a KeyID that is empty, longer than 255 bytes or the master key's ("master").

func LowerSeats

func LowerSeats(st *store.Store, modules []ext.Module) func(ctx context.Context, tenantID int64, now time.Time) error

LowerSeats is, for the seat worker, how a tenant's paid seats come down once a seat is freed (store.SeatCheck): when its plan is sold by the seat, it asks the billing module for the seats the tenant uses, never fewer than the plan's least, keeping the company sign-in add-on as it is. It asks even when that is the number the daemon last heard of: seats bought for an invitation moments ago may not be reported yet (Host.SetPlan), and asking for the number the subscription has already changes nothing (ext.Billing.ChangePlan), so asking twice is safe. The seats are not kept up for company sign-in: fewer than it comes with, and no add-on, end it once reported (companySignInAllowed). Nil in a build that sells no plans.

func NewHandler

func NewHandler(o Options) http.Handler

NewHandler returns the daemon's HTTP routes.

func PlanFeature

func PlanFeature(st *store.Store, modules []ext.Module, feature string) func(ctx context.Context, tenantID int64) bool

PlanFeature is, for actions.Exec.Notices, whether a tenant may use feature: every tenant's in a build that sells no plans. A failure to read the plan is logged and refuses.

Types

type ModelSource

type ModelSource interface {
	Live(ctx context.Context, tenantID int64) (router *models.Router, minConfidence float64)
	RouterFor(ctx context.Context, tenantID int64, spec string) *models.Router
	Composer(ctx context.Context, tenantID int64) (models.Generator, error)
}

ModelSource is how this package reaches the models (settings.Settings implements it): the decision router in force, the router of a rule's own model, and the generative model the composer writes with.

type Options

type Options struct {
	Store         *store.Store
	SecureCookies bool // set when the UI is not served from localhost
	// TrustedProxies are the peers whose X-Forwarded-For header is believed when counting
	// failed sign-ins (MAILRULES_TRUSTED_PROXIES). Empty: the header is never read.
	TrustedProxies []netip.Prefix
	Now            func() time.Time // nil means time.Now

	Hub      *events.Hub        // the SSE stream's source; nil = a private hub nothing publishes to
	Exec     *actions.Exec      // undo and corrections: the only way this package changes a mailbox
	Settings *settings.Settings // the settings the user changes at runtime
	Models   ModelSource        // the models the composer and tester use; nil = Settings
	Metrics  *telemetry.Metrics // nil = a private registry
	Version  string             // shown in GET /api/settings

	// StartCheck starts a cleanup check of an account in the background and returns it,
	// running (worker.Manager.StartCheck). Checks holds the account checks in memory, and
	// SortAll applies finished checks' kept rows, one undoable batch per mailbox, all started
	// or none (worker.Manager.SortAll).
	StartCheck func(c worker.Cleanup, fingerprint string, run worker.CheckFunc) (*worker.Check, error)
	Checks     *worker.CheckStore
	SortAll    func(ctx context.Context, runs []worker.SortRun) ([]store.Batch, error)
	// Connect logs in to a mail server with credentials that are not stored yet, trying
	// the usernames the preset allows, and returns the connection with the username that worked.
	Connect func(ctx context.Context, acct store.Account, password string) (mail.Mailbox, string, error)
	// ConnectOAuth logs in to a one-click mailbox (store.Account.OAuth) through the module
	// that signs in to its preset. secret nil: the account's stored secret, replaced in the
	// store when the module rotates it. Otherwise a secret not stored yet, replaced in place
	// when the module rotates it, so what is stored afterwards is the one that works.
	ConnectOAuth func(ctx context.Context, acct store.Account, secret *string) (mail.Mailbox, error)
	// Resolver looks up the server a person names, which in the hosted build must be on
	// the public internet (publicnet.Check); nil is the system's resolver.
	Resolver publicnet.Resolver
	// StartAccount (re)starts watching an account; StopAccount stops it and waits until
	// mail already queued is finished.
	StartAccount func(acct store.Account)
	StopAccount  func(accountID int64)
	// Modules are the features compiled in from outside this repository. Their routes are
	// served like the built-in ones, and each one's name is on in GET /api/settings
	// features. A route of the contract that only a module provides is refused with 404
	// not_available while no module serves it.
	Modules []ext.Module
	// Summary is the summary email; nil = one built from Settings.Env that cannot send.
	Summary *summary.Service
	// Unsubscriber calls the one-click unsubscribe links Senders offers; nil = one that
	// reaches only the public internet (unsubscribe.New with Resolver).
	Unsubscriber unsubscribe.Unsubscriber
}

Options configures the HTTP handler.