Documentation
¶
Overview ¶
Package openrails reads OpenRails facts using an inbox-owned cursor. Hosts own identity mapping, optional-event policy and scheduling.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrCursorExpired = errors.New("openrails notifications: event cursor expired; resync required")
ErrCursorExpired requires an explicit destination resync. Consume never silently starts over or skips a lost interval.
var ErrInboxHandoffRequired = errors.New("openrails notifications: finish the explicit inbox handoff before retiring polling jobs")
ErrInboxHandoffRequired means old source facts remain beyond the saved inbox cursor. Explicitly Consume those pages before retiring the old poller.
Functions ¶
func BillingLifecycle ¶ added in v0.89.0
BillingLifecycle selects unexpected billing outcomes. OpenRails keeps its complete event history; ContentKit avoids notifying about a user's own click.
Types ¶
type Backend ¶ added in v0.89.0
Backend reads a merchant-bound log without changing source state. Expired and reset cursors return ErrCursorExpired.
type ConsumeOptions ¶
type ConsumeResult ¶
type Event ¶
type Event struct {
ID string `json:"id"`
MerchantID string `json:"merchant_id"`
Source string `json:"source"`
EventType string `json:"type"`
Version int `json:"version"`
Subject EventSubject `json:"subject"`
Data json.RawMessage `json:"data"`
CreatedAt time.Time `json:"occurred_at"`
CustomerID string `json:"-"`
// Nil means unknown historical ownership, not a native account.
AccountIssuer *string `json:"-"`
ActionRequested bool `json:"-"`
Optional bool `json:"-"`
}
Event is the retained source snapshot. Customer fields are derived from its data, never fetched from a billing row which may have since been deleted.
type EventSubject ¶ added in v0.116.0
type Inbox ¶ added in v0.116.0
type Inbox interface {
EventCursor(context.Context, notify.OriginScope) (string, error)
ImportEvents(context.Context, notify.OriginScope, string, string, []notify.Input) (notification.EventImportResult, error)
}
Inbox owns both publication and progress. Implementations must commit the effects and cursor atomically; the producer stores no consumer state.
type Options ¶
type Options struct {
Backend Backend
Name string
URL string
MerchantID string
Client *http.Client
Token func(context.Context) (string, error)
}
Options binds one trusted deployment and merchant. Token supplies a merchant-authorized application token; Client can authenticate instead. URL precedes /v1. A native Backend needs no URL or network credentials.
type RecipientMapper ¶
RecipientMapper resolves verified source coordinates to a local account. False deliberately skips a fact; errors leave the whole page for retry. Email equality alone must never establish the association.
type Source ¶
type Source struct {
// contains filtered or unexported fields
}
func New ¶
New validates the trusted source. HTTP requests have a fifteen-second deadline and refuse redirects to keep credentials on that deployment.
func (*Source) Consume ¶
func (s *Source) Consume(ctx context.Context, destination Inbox, mapper RecipientMapper, opts ConsumeOptions) (ConsumeResult, error)
Consume reads one page and atomically commits its notices and continuation. A failed mapping or write commits neither. Other source facts are skipped but advance the cursor, so a busy host-event log cannot stall the inbox.
func (*Source) Origin ¶ added in v0.89.0
func (s *Source) Origin() notify.OriginScope
func (*Source) RetireInboxSync ¶ added in v0.127.0
func (s *Source) RetireInboxSync(ctx context.Context, pool *pgxpool.Pool, riverSchema, namespace string, destination Inbox) error
RetireInboxSync cancels only this source's unfinished legacy polling jobs. Call during an explicit stopped-writer migration after the final Consume pass and before enabling direct producer publication. It is not a runtime worker. Terminal history, other sources, general events and inbox receipts survive.
Source Files