activity

type Actor struct {
	// ID is the stable identifier filters match on (a user id, "ci",
	// "converger").
	ID string
	// Name is how the actor is shown. Empty falls back to ID.
	Name string
	// Kind classifies the actor.
	Kind ActorKind
}

type ActorKind string

type ClaimsLookup = func(ctx context.Context) (*auth.Claims, bool)

type DB interface {
	Exec(ctx context.Context, query string, args ...any) (sql.Result, error)
	Query(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}

type Declaration struct {
	// None is the reason the rpc records no activity. When set, every other
	// field is zero.
	None string
	// Verb is the action token.
	Verb string
	// TargetKind is the target's type.
	TargetKind string
	// TargetID, TargetLabel, Env and Scope locate their values in the
	// request or response. A zero Path is absent (TargetID never is).
	TargetID, TargetLabel, Env, Scope Path
	// Detail lists the paths copied into Event.Detail.
	Detail []Path
	// Writer says who writes the event.
	Writer WriterKind
	// Implied reports a declaration derived from forge's CRUD shape rather
	// than written in an option.
	Implied bool
}

type Deps struct {
	// Principal names each call's caller and scope. Required: see
	// [Principal] for why there is no default.
	Principal Principal
	// Writer persists events. nil is LogWriter(Logger): events are logged,
	// not stored.
	Writer Writer
	// ViaFrom names the channel a request came through. nil is
	// [DefaultVia].
	ViaFrom func(ctx context.Context, req connect.AnyRequest) string
	// Logger reports failed writes and malformed declarations. nil is
	// slog.Default().
	Logger *slog.Logger
	// Meter counts failed writes (forge_activity_write_failures_total). nil
	// is the global meter provider's.
	Meter metric.Meter
	// WriteTimeout bounds one write. Zero is DefaultWriteTimeout.
	WriteTimeout time.Duration
}

type Event struct {
	// ID is assigned by the store on write; set on events List returns.
	ID string
	// OccurredAt is when the action happened. Zero is "now" at write.
	OccurredAt time.Time
	// Scope is what reads filter by: an org, a project. Empty is
	// unscoped.
	Scope string
	// Actor performed the action.
	Actor Actor
	// Verb is the action, a lower_snake token: "promote", "rotate".
	Verb string
	// Target is the object acted on.
	Target Target
	// Env is the environment the action happened in. Empty is a
	// project-level event.
	Env string
	// Via is the channel the action came through: "console", "cli", "ci",
	// "api", or a system's own name.
	Via string
	// Procedure is the RPC that recorded the event, when one did.
	Procedure string
	// Detail carries small, declared extras ({"from_env": "e2e"}).
	Detail map[string]string
	// TraceID ties the event to the request's trace, when there was one.
	TraceID string
}

type Filter struct {
	Scope string
	// IncludeAncestors also matches events scoped to each ancestor of Scope:
	// a project's feed ("org_1/billing") then includes the events of its org
	// ("org_1"), such as an alert receiver created org-wide.
	IncludeAncestors bool
	// IncludeDescendants also matches events scoped below Scope: an org's
	// feed ("org_1") then includes every project's ("org_1/billing", ...).
	IncludeDescendants bool
	ActorID            string
	ActorKind          ActorKind
	Verb               string
	TargetKind         string
	TargetID           string
	Env                string
	// Envs matches any of the listed environments (AND-combined with Env).
	// Empty does not filter.
	Envs []string
	Via  string
	// Since and Until bound OccurredAt (inclusive, exclusive). Zero is
	// unbounded.
	Since, Until time.Time
	// PageSize is the page length. Zero is DefaultPageSize; it is capped at
	// MaxPageSize.
	PageSize int
	// PageToken continues from a previous page's NextPageToken.
	PageToken string
}

type Page struct {
	Events []Event
	// NextPageToken continues the listing; empty on the last page.
	NextPageToken string
}

type Path struct {
	// Spec is the path as written ("response.release.version").
	Spec string
	// Response reports a path resolved against the response message.
	Response bool
	// contains filtered or unexported fields
}

type Principal interface {
	// Actor is the caller of the call on ctx.
	Actor(ctx context.Context) Actor
	// Scope is the scope (an org, a project) of an event whose declaration
	// names no scope path.
	Scope(ctx context.Context) string
}

type Store struct {
	// contains filtered or unexported fields
}

type StoreOption func(*Store)

type Target struct {
	// Kind is the object's type, a lower_snake token: "release", "secret".
	Kind string
	// ID identifies the object within its kind.
	ID string
	// Label is a human-readable name. Empty falls back to ID.
	Label string
}

type Writer interface {
	Write(ctx context.Context, ev Event) error
}

type WriterFunc func(ctx context.Context, ev Event) error

type WriterKind int