Documentation
¶
Overview ¶
Package app composes the application: it registers every singleton in the dependency container and starts and stops the servers, the event router and the job workers.
Index ¶
- Variables
- type App
- func (a *App) Accounts() (*accounts.Accounts, error)
- func (a *App) Bus() (*events.Bus, error)
- func (a *App) Close(ctx context.Context) error
- func (a *App) CreateOwner(ctx context.Context, email, name string) (string, error)
- func (a *App) CreateStaffMember(ctx context.Context, email string) (string, error)
- func (a *App) Done() <-chan error
- func (a *App) IssueServiceCredential(ctx context.Context, in staff.IssueInput) (*staff.Issued, error)
- func (a *App) Reencrypt(ctx context.Context) ([]rekey.Count, error)
- func (a *App) ResetSecondFactor(ctx context.Context, email string) (bool, error)
- func (a *App) ResetStaffTOTP(ctx context.Context, email string) error
- func (a *App) RevokeServiceCredential(ctx context.Context, id int64) error
- func (a *App) RotateServiceCredential(ctx context.Context, id int64, expiresAt *time.Time) (*staff.Issued, error)
- func (a *App) ServiceCredentials(ctx context.Context, name string) ([]*ent.ServiceCredential, error)
- func (a *App) Shutdown(ctx context.Context) *do.ShutdownReport
- func (a *App) Start(ctx context.Context) error
- func (a *App) SuspendWorkspace(ctx context.Context, publicID string, by suspension.Actor, reason string) (bool, error)
- func (a *App) UnsuspendWorkspace(ctx context.Context, publicID string, by suspension.Actor) (bool, error)
- type Option
Constants ¶
This section is empty.
Variables ¶
var ErrAlreadyStarted = errors.New("app: already started")
ErrAlreadyStarted means Start was called a second time; an App starts once.
var ErrE2EOnly = errors.New("app: option is only valid in the " + config.EnvE2E + " environment")
ErrE2EOnly means an end-to-end-only option was passed to an app that is not the e2e profile.
var ErrNotServable = errors.New("app: this app has no servers to start")
ErrNotServable means Start was called on an app that has no servers (the command app).
Functions ¶
This section is empty.
Types ¶
type App ¶
type App struct {
Config *config.Config
Server *http.Server
// Metrics is the opt-in Prometheus listener (ADR 0018); nil when SPHERICON_METRICS_ADDR
// is empty and for the command app.
Metrics *telemetry.MetricsServer
// Internal is the opt-in internal listener: the edge's TLS ask (ADR 0038, always) and the
// service endpoints (ADR 0026, with the `staff` license); nil when SPHERICON_INTERNAL_ADDR
// is empty and for the command app.
Internal *sidelistener.Server
// contains filtered or unexported fields
}
func NewCommandApp ¶
NewCommandApp builds the minimal app the commands need (config, database, ent client, system sender) without the HTTP server, the event router or the job workers. Providers are lazy, so only what a command invokes is ever constructed; that keeps `sphericon workspace …` quick to start and to shut down.
func (*App) Accounts ¶
Accounts is the product's Accounts module from the DI container, for harnesses that arrange users and Workspaces through the same instance the HTTP surface runs on (the end-to-end suite), so they open no second connection pool.
func (*App) Bus ¶
Bus is the event bus from the DI container, for harnesses that must change data inside a transaction (events.Bus.WithinScopedTx) like the product's own write paths.
func (*App) Close ¶
Close cancels the event router and the job workers, waits for them to stop, shuts the HTTP servers down and then the container. Safe to call more than once and after a failed Start; every call returns the first call's result.
func (*App) CreateOwner ¶
CreateOwner makes a Verified User with its first Workspace and a one-time password (ADR 0042): the way the first Owner of an Instance that closed sign-up comes to exist.
func (*App) CreateStaffMember ¶
CreateStaffMember makes a platform Staff member (ADR 0026) and returns its one-time password: the only way a Staff member comes to exist (there is no signup). It refuses a duplicate email and an instance without the `staff` license.
func (*App) Done ¶
Done delivers, once, how the public server ended. A failure to serve arrives as an error; after a graceful Close the server ends cleanly and a nil error arrives, so a receiver must read nil as "stopped", not "still running". Nothing arrives if Start failed before serving. A binary waits on it next to its signals.
func (*App) IssueServiceCredential ¶
func (a *App) IssueServiceCredential(ctx context.Context, in staff.IssueInput) (*staff.Issued, error)
IssueServiceCredential creates a Service credential (ADR 0026) and returns it with its value, shown once. Only the Staff member's command line makes one: no endpoint can.
func (*App) Reencrypt ¶
Reencrypt seals every stored secret under the primary key of the encryption keyset (`sphericon encryption-key reencrypt`) and returns what it did per column.
func (*App) ResetSecondFactor ¶
ResetSecondFactor clears the Second factor and Recovery codes of the User with this email and ends every session of theirs (ADR 0020), recorded as `user.second_factor_reset` by the Staff member "cli" in each of their Workspaces. It reports whether anything changed: a User without a Second factor is left as is.
func (*App) ResetStaffTOTP ¶
ResetStaffTOTP clears the TOTP of the Staff member with this email and ends its sessions (ADR 0026): the only way a lost TOTP is reset. The Staff member re-enrols at next login. staff.ErrNotFound for an unknown email, ErrNotLicensed without the license.
func (*App) RevokeServiceCredential ¶
RevokeServiceCredential ends a Service credential.
func (*App) RotateServiceCredential ¶
func (a *App) RotateServiceCredential(ctx context.Context, id int64, expiresAt *time.Time) (*staff.Issued, error)
RotateServiceCredential issues a new credential with the name and scopes of an active one, leaving the old one active until it is revoked.
func (*App) ServiceCredentials ¶
func (a *App) ServiceCredentials(ctx context.Context, name string) ([]*ent.ServiceCredential, error)
ServiceCredentials lists the Service credentials with their state, narrowed to one service's by name when set.
func (*App) Start ¶
Start brings the application up and returns without blocking: it binds the metrics listener, starts the domain-event router and the job queue, then serves the public HTTP server. It returns the first startup error after unwinding whatever it had already started (the container included), so a failed Start leaves nothing running.
Start owns its cancellation: it derives its own context from ctx, and Close cancels it. Done reports how the public server ends; Close stops everything. An App starts once: a second Start returns ErrAlreadyStarted, whether or not the first succeeded.
func (*App) SuspendWorkspace ¶
func (a *App) SuspendWorkspace(ctx context.Context, publicID string, by suspension.Actor, reason string) (bool, error)
SuspendWorkspace freezes a Workspace's outbound sending (ADR 0007) and tells its owner(s) through the system sender. It reports whether anything changed; an already-suspended Workspace is left as it was and the owner is not told twice. If the notice cannot be sent the suspension still stands and the error says so.
func (*App) UnsuspendWorkspace ¶
func (a *App) UnsuspendWorkspace(ctx context.Context, publicID string, by suspension.Actor) (bool, error)
UnsuspendWorkspace lifts a Workspace's suspension; held sends resume on their own.
type Option ¶
type Option func(*options)
Option customises how New builds the App.
func WithE2EDKIMLookup ¶
func WithE2EDKIMLookup() Option
WithE2EDKIMLookup swaps the DKIM DNS lookup for the development one, which echoes a Sending domain's own stored key, so the end-to-end suite verifies domains without real DNS while the development flag stays off. New refuses it outside the e2e profile, so it cannot be wired into a production configuration.
func WithListener ¶
WithListener makes the App serve on a listener the caller already opened (a free port, say). The configured public URL (SPHERICON_APP_URL, the base of unsubscribe, confirm and tracking links) and PORT are derived from the listener's address, so the order is: open the listener, then New, then Start. Close closes the listener.
Source Files