subscription

type Actor struct {
	Kind       string `json:"kind"`
	ID         string `json:"id,omitempty"`
	OnBehalfOf string `json:"on_behalf_of,omitempty"`
}

type Apps interface {
	ByID(ctx context.Context, appID string) (state.App, bool, error)
}

type Authorizer interface {
	CheckControl(ctx context.Context, p authz.Principal, appID string, verb authz.Verb) error
	CheckInstall(ctx context.Context, p authz.Principal, verb authz.Verb) error
	Allows(ctx context.Context, p authz.Principal, appID string, verb authz.Verb) (bool, error)
	AllowsInstall(ctx context.Context, p authz.Principal, verb authz.Verb) (bool, error)
}

type Channel struct {
	ID   string `json:"id"`
	Kind string `json:"kind"`
}

type CreateRequest struct {
	// AppID is the app it is about; empty subscribes install-wide.
	AppID       string   `json:"app_id,omitempty"`
	Events      []string `json:"events"`
	Destination string   `json:"destination"`
	URL         string   `json:"url,omitempty"`
	AdapterID   string   `json:"adapter_id,omitempty"`
	Description string   `json:"description,omitempty"`

	// Channel is the channel an adapter whose capabilities say Channels
	// posts to, from GET /notify/{id}/channels; refused for every other.
	Channel string `json:"channel,omitempty"`

	// How a webhook is sent (R-375). Header values are secret.Value: they
	// are read from the request, sealed, and never written back out.
	Method          string                  `json:"method,omitempty"`
	ContentType     string                  `json:"content_type,omitempty"`
	Headers         map[string]secret.Value `json:"headers,omitempty"`
	PayloadTemplate string                  `json:"payload_template,omitempty"`
}

type Created struct {
	state.Subscription
	SigningKey *secretOnce `json:"signing_key,omitempty"`
}

type DeliveryDetail struct {
	state.Delivery
	// Payload is the body as it is sent: JSON when it is JSON, otherwise
	// the text of a templated body.
	Payload any `json:"payload"`
}

type Deployments interface {
	ByID(ctx context.Context, deploymentID string) (state.Deployment, bool, error)
}

type Destination struct {
	ID       string             `json:"id"`
	Name     string             `json:"name"`
	Kind     string             `json:"kind"`
	Audience api.NotifyAudience `json:"audience"`

	// Channels says a subscription to it names a channel, from
	// GET /notify/{id}/channels.
	Channels bool `json:"channels,omitempty"`
}

type Dispatcher struct {
	Events        *state.Events
	Subscriptions *state.Subscriptions
	Deliveries    *state.Deliveries
	Keys          *state.SubscriptionSecrets

	// Tokens resolves an account token that owns a subscription (R-060).
	Tokens interface {
		Active(ctx context.Context, tokenID string) (state.Token, bool, error)
	}

	// ExternalURL is how a browser reaches Pando, for the link in each
	// delivery. Empty sends none.
	ExternalURL string

	// Who Pando's own failure notifications go to (announce.go). Each is
	// optional; without one, those people are not told.
	Deployments Deployments
	Holders     VerbHolders
	TokenOwners TokenOwners

	Authz    Authorizer
	Policy   PolicyLoader
	Apps     Apps
	Users    Users
	Groups   Groups
	Registry *api.Registry

	// Notifiers are the notification adapters a subscription sends through.
	// Nil reads them from Registry.
	Notifiers Notifiers

	// Notifier tells a subscription's owner it was turned off. Optional.
	Notifier interface {
		Notify(ctx context.Context, n api.Notification) error
	}

	Audit  func(ctx context.Context, e audit.Event)
	Clock  clock.Clock
	Logger *zap.Logger

	// Client sends webhooks. Nil builds the guarded client (R-372); tests
	// supply their own only to reach a local server, with policy allowing it.
	Client *http.Client

	// Interval is how often the outbox is read when it was empty last time.
	Interval time.Duration

	// SubscriptionCache is how long the list of enabled subscriptions is
	// reused for routing [P]: when zero, WatchedSubscriptionCache while Run is
	// listening for changes (migration 61) and three seconds while it is not;
	// never when negative. Routing used to read it — three joins — on every
	// pass of every replica (issue #72). It decides only which deliveries are queued;
	// whether one is sent is decided at send time, as its owner, now (R-368),
	// and a subscription turned off is not sent to however it was routed.
	SubscriptionCache time.Duration

	// Senders is how many deliveries are sent at once. Eight when zero.
	Senders int
	// contains filtered or unexported fields
}

type Envelope struct {
	ID         string         `json:"id"`
	Type       string         `json:"type"`
	OccurredAt time.Time      `json:"occurred_at"`
	App        *EnvelopeApp   `json:"app,omitempty"`
	Actor      Actor          `json:"actor"`
	Data       map[string]any `json:"data"`

	// Link is where in the console to look, when Pando's external_url is
	// set (R-369).
	Link string `json:"link,omitempty"`
}

type EnvelopeApp struct {
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
	Slug string `json:"slug,omitempty"`
}

type FeedItem struct {
	Envelope
	Subject string                  `json:"subject"`
	Body    string                  `json:"body,omitempty"`
	Fields  []api.NotificationField `json:"fields,omitempty"`
}

type Groups interface {
	GroupsForUser(ctx context.Context, userID string) ([]string, error)
}

type Inbox struct {
	Store *state.Notifications
}

type InboxPage struct {
	Notifications []state.Notification `json:"notifications"`
	Unread        int                  `json:"unread"`
	NextBefore    string               `json:"next_before"`
}

type Kind struct {
	Kind        api.NotificationKind `json:"kind"`
	Label       string               `json:"label"`
	Description string               `json:"description"`
	DefaultOn   bool                 `json:"default_on"`
}

type ListRequest struct {
	AppID string
	// Everyone lists every person's subscriptions, which needs
	// install.events.manage. Otherwise the list is the caller's own.
	Everyone bool
	// Page is which page, newest first (issue #72).
	Page state.Page
}

type Notifiers interface {
	Notify(ctx context.Context, id string) (api.NotifyAdapter, bool)
	Usable(ctx context.Context) ([]notifyconn.Adapter, error)
}

type PolicyLoader interface {
	Load(ctx context.Context) (policy.Document, error)
}

type Preferences interface {
	List(ctx context.Context, userID string) ([]state.NotificationPreference, error)
}

type PreferencesView struct {
	Kinds    []Kind                         `json:"kinds"`
	Channels []Channel                      `json:"channels"`
	Choices  []state.NotificationPreference `json:"choices"`
}

type Resolver interface {
	LookupNetIP(ctx context.Context, network, host string) ([]netip.Addr, error)
}

type Result struct {
	StatusCode int
	Err        error
	Duration   time.Duration
}

type Router struct {
	Registry *api.Registry

	// Notifiers are the notification adapters. Nil reads them from Registry.
	Notifiers   Notifiers
	Preferences Preferences
	Users       Users
	Logger      *zap.Logger
}

type Service struct {
	Subscriptions *state.Subscriptions
	Deliveries    *state.Deliveries
	Events        *state.Events
	Keys          *state.SubscriptionSecrets

	// ExternalURL is how a browser reaches Pando, for links. Empty sends none.
	ExternalURL string
	Prefs       *state.NotificationPreferences

	Authz    Authorizer
	Policy   PolicyLoader
	Apps     Apps
	Registry *api.Registry

	// Notifiers are the notification adapters a subscription may send
	// through. Nil reads them from Registry.
	Notifiers Notifiers

	// Resolver looks webhook hosts up when one is saved. Nil uses the
	// system resolver.
	Resolver Resolver

	Audit  func(ctx context.Context, e audit.Event)
	Clock  clock.Clock
	Logger *zap.Logger
}

type TemplateData struct {
	ID         string
	Type       string
	OccurredAt time.Time
	App        EnvelopeApp
	Actor      Actor
	Data       map[string]any

	// Subject, Body and Fields are the event as a notification describes it.
	Subject string
	Body    string
	Fields  []api.NotificationField
	Link    string

	// Envelope is Pando's own body, for a template that wraps it.
	Envelope Envelope
}

type TokenOwners interface {
	Owner(ctx context.Context, tokenID string) (string, bool, error)
}

type UpdateRequest struct {
	Events          *[]string                `json:"events,omitempty"`
	URL             *string                  `json:"url,omitempty"`
	AdapterID       *string                  `json:"adapter_id,omitempty"`
	Channel         *string                  `json:"channel,omitempty"`
	Description     *string                  `json:"description,omitempty"`
	Enabled         *bool                    `json:"enabled,omitempty"`
	Method          *string                  `json:"method,omitempty"`
	ContentType     *string                  `json:"content_type,omitempty"`
	Headers         *map[string]secret.Value `json:"headers,omitempty"`
	PayloadTemplate *string                  `json:"payload_template,omitempty"`
}

type Users interface {
	ByID(ctx context.Context, userID string) (state.User, bool, error)
}

type VerbHolders interface {
	InstallVerbHolders(ctx context.Context, verb authz.Verb) ([]string, error)
}