githubapp

type Access ¶

type Access[T any] struct {
	Visibility Visibility
	Value      T
}

Access wraps a read-model result with its disclosure class.

type AuthoritativeReader ¶

type AuthoritativeReader interface {
	Refresh(context.Context, WebhookDelivery) error
}

AuthoritativeReader refreshes the GitHub App's authoritative view before an action is queued. A cache hit alone must never satisfy this call.

type Dashboard ¶

type Dashboard struct {
	GeneratedAt time.Time `json:"generated_at"`
	Summary     Summary   `json:"summary"`
	Links       []Link    `json:"links,omitempty"`
}

Dashboard is the top-level dashboard response.

type DeliveryStore ¶

type DeliveryStore interface {
	HasDelivery(context.Context, string) (bool, error)
	CommitDeliveryAndWakeup(context.Context, string, Wakeup) (bool, error)
}

DeliveryStore must be backed by durable storage. HasDelivery is a cheap preflight that avoids repeating an authoritative GitHub read for a redelivery. CommitDeliveryAndWakeup atomically records the delivery ID and persists a wakeup coalesced by its scope key. It returns false when a concurrent request committed the same delivery first.

type Event ¶

type Event struct {
	ID         uint64          `json:"id"`
	Type       EventType       `json:"type"`
	Visibility Visibility      `json:"visibility"`
	At         time.Time       `json:"at"`
	Repository string          `json:"repository,omitempty"`
	Task       string          `json:"task,omitempty"`
	Operation  string          `json:"operation,omitempty"`
	Session    string          `json:"session,omitempty"`
	Severity   string          `json:"severity,omitempty"`
	Payload    json.RawMessage `json:"payload"`
}

Event is an SSE record. ID is a durable monotonic cursor, not a timestamp. Payload is only serialized after the viewer passes its visibility check.

type EventFilter ¶

type EventFilter struct {
	After      uint64
	Since      time.Time
	Repository string
	Task       string
	Operation  string
	Session    string
	Severity   string
}

EventFilter selects one resumable daemon/direct-WB event sequence. Work Logs remain immutable per-task evidence; this filter is transient monitoring only.

type EventSource ¶

type EventSource interface {
	Replay(context.Context, EventFilter) ([]Event, error)
	Subscribe(context.Context, EventFilter) (<-chan Event, error)
}

EventSource durably replays events strictly after a cursor, then exposes a live subscription. Implementations must retain enough history for reconnects and issue globally monotonic IDs across daemon generations.

type EventType ¶

type EventType string

EventType classifies a live Workbench daemon update. WebSocket is reserved for later bidirectional controls such as cancel and reprioritize.

const (
	EventQueue            EventType = "queue"
	EventJobPhase         EventType = "job.phase"
	EventJobProgress      EventType = "job.progress"
	EventCI               EventType = "ci"
	EventCleanup          EventType = "cleanup"
	EventSync             EventType = "sync"
	EventDaemonGeneration EventType = "daemon.generation"
)

type FirestoreBackend ¶ added in v0.102.0

type FirestoreBackend interface {
	Get(context.Context, string, string, any) (bool, error)
	Query(context.Context, string, map[string]any, int, any) error
	Set(context.Context, string, string, any) error
	UpdateAtomic(context.Context, func(FirestoreTransaction) error) error
}

FirestoreBackend is the deliberately small seam implemented by the host's Firestore client. Values are decoded into out by the backend. UpdateAtomic must provide Firestore transaction semantics.

type FirestoreProjectionDeliveryStore ¶ added in v0.102.0

type FirestoreProjectionDeliveryStore struct {
	Backend FirestoreBackend
	Now     func() time.Time
	Lease   time.Duration
}

FirestoreProjectionDeliveryStore provides the atomic claim and coalesced wakeup used by ProjectionEngine. An expired claim is recoverable.

func (store FirestoreProjectionDeliveryStore) ClaimDelivery(ctx context.Context, id string) (bool, error)

func (store FirestoreProjectionDeliveryStore) CommitDeliveryAndWakeup(ctx context.Context, id string, wakeup Wakeup) (bool, error)

func (store FirestoreProjectionDeliveryStore) HasDelivery(ctx context.Context, id string) (bool, error)

func (store FirestoreProjectionDeliveryStore) ReleaseDelivery(ctx context.Context, id string) error

type FirestoreProjectionStore ¶ added in v0.102.0

type FirestoreProjectionStore struct{ Backend FirestoreBackend }

FirestoreProjectionStore maps the documented Workbench collections to the host backend. The adapter contains no cloud.google.com imports, keeping the provider portable and letting Sneat Go supply its configured client.

func (store FirestoreProjectionStore) GetLeaderboard(ctx context.Context, metric string) (LeaderboardDocument, error)

func (store FirestoreProjectionStore) GetProjection(ctx context.Context, scope Scope, id string) (ProjectionDocument, error)

func (store FirestoreProjectionStore) ListProjections(ctx context.Context, scope Scope) ([]ProjectionDocument, error)

func (store FirestoreProjectionStore) ListPublicLatestMerges(ctx context.Context, limit int) (PublicLatestMerges, error)

func (store FirestoreProjectionStore) ListSeries(ctx context.Context, scope Scope, id, metric string) (SeriesDocument, error)

type FirestoreProjectionWriter ¶ added in v0.102.0

type FirestoreProjectionWriter struct{ Backend FirestoreBackend }

FirestoreProjectionWriter applies complete batches by stable document key. Set is intentionally idempotent, so a retry after a crash cannot duplicate projections or public merges.

func (writer FirestoreProjectionWriter) WriteLatestMerges(ctx context.Context, deliveryID string, records []LatestMerge) error

func (writer FirestoreProjectionWriter) WriteOrganizations(ctx context.Context, deliveryID string, records []ProjectionDocument) error

func (writer FirestoreProjectionWriter) WriteRepositories(ctx context.Context, deliveryID string, records []ProjectionDocument) error

type FirestoreTransaction ¶ added in v0.102.0

type FirestoreTransaction interface {
	Get(context.Context, string, string, any) (bool, error)
	Set(context.Context, string, string, any) error
}

type HandlerOptions ¶

type HandlerOptions struct {
	Service        Service
	ViewerResolver ViewerResolver
	AllowedOrigin  string
}

HandlerOptions supplies the narrow host bindings for the public API.

type LatestMerge ¶

type LatestMerge struct {
	Repository     string    `json:"repository" firestore:"repository"`
	PullRequest    int       `json:"pull_request" firestore:"pull_request"`
	MergedAt       time.Time `json:"merged_at" firestore:"merged_at"`
	PullRequestURL string    `json:"pull_request_url,omitempty" firestore:"pull_request_url,omitempty"`
	IssueURL       string    `json:"issue_url,omitempty" firestore:"issue_url,omitempty"`
	MergeCommitSHA string    `json:"merge_commit_sha,omitempty" firestore:"merge_commit_sha,omitempty"`
	MergeCommitURL string    `json:"merge_commit_url,omitempty" firestore:"merge_commit_url,omitempty"`
	ReleaseURL     string    `json:"release_url,omitempty" firestore:"release_url,omitempty"`
	ReceiptURL     string    `json:"receipt_url,omitempty" firestore:"receipt_url,omitempty"`
}

LatestMerge gives the dashboard every navigable artifact around a merge.

type Leaderboard ¶

type Leaderboard struct {
	Metric  string             `json:"metric"`
	Entries []LeaderboardEntry `json:"entries"`
}

Leaderboard groups ranked values for a requested metric.

type LeaderboardDocument ¶ added in v0.100.0

type LeaderboardDocument struct {
	Metric     string             `json:"metric" firestore:"metric"`
	Entries    []LeaderboardEntry `json:"entries" firestore:"entries"`
	PublicOnly bool               `json:"public_only" firestore:"public_only"`
}

type LeaderboardEntry ¶

type LeaderboardEntry struct {
	Rank        int    `json:"rank" firestore:"rank"`
	SubjectID   string `json:"subject_id" firestore:"subject_id"`
	DisplayName string `json:"display_name" firestore:"display_name"`
	Value       int64  `json:"value" firestore:"value"`
}

LeaderboardEntry is intentionally small so public leaderboards do not leak private repository names or private activity counts.

type Link ¶

type Link struct {
	Kind string `json:"kind"`
	Href string `json:"href"`
}

Link is a canonical GitHub, release, or Workbench receipt reference.

type MembershipResolver ¶ added in v0.100.0

type MembershipResolver interface {
	Member(context.Context, Viewer, Scope, string) (bool, error)
}

MembershipResolver proves GitHub installation membership for one canonical subject. A Firebase-authenticated host maps Viewer.UserID to GitHub identity; the provider never trusts browser headers or public GitHub visibility.

type ProjectionDeliveryStore ¶ added in v0.101.0

type ProjectionDeliveryStore interface {
	DeliveryStore
	ClaimDelivery(context.Context, string) (bool, error)
	ReleaseDelivery(context.Context, string) error
}

ProjectionDeliveryStore extends DeliveryStore with an atomic in-flight claim. ClaimDelivery returns false for a committed or currently claimed delivery. ReleaseDelivery makes refresh/write failures retryable; the implementation must retain its append-only audit record.

type ProjectionDocument ¶ added in v0.100.0

type ProjectionDocument struct {
	Scope             Scope              `json:"scope" firestore:"scope"`
	ID                string             `json:"id" firestore:"id"`
	DisplayName       string             `json:"display_name" firestore:"display_name"`
	Summary           Summary            `json:"summary" firestore:"summary"`
	UpdatedAt         time.Time          `json:"updated_at" firestore:"updated_at"`
	PublicOptIn       bool               `json:"public_opt_in" firestore:"public_opt_in"`
	PublicEligibility *PublicEligibility `json:"public_eligibility,omitempty" firestore:"public_eligibility,omitempty"`
}

ProjectionDocument is the durable, privacy-classified summary written by a Workbench-owned projector. Public responses require PublicOptIn; private responses require the host membership resolver below.

type ProjectionEngine ¶ added in v0.101.0

type ProjectionEngine struct {
	Deliveries          ProjectionDeliveryStore
	Reader              ProjectionReader
	Writer              ProjectionWriter
	AuthoritativeReader AuthoritativeReader
	WebhookSecret       []byte
}

ProjectionEngine coordinates authoritative refresh, durable projection writes, and delivery receipt publication. It deliberately does not import GitHub, Firebase, or Firestore clients.

func (engine ProjectionEngine) Process(ctx context.Context, delivery WebhookDelivery, signature string) (queued bool, processErr error)

type ProjectionReader ¶ added in v0.101.0

type ProjectionReader interface {
	RefreshProjection(context.Context, WebhookDelivery) (ProjectionSnapshot, error)
}

ProjectionReader refreshes and returns the authoritative records for a delivery. Implementations may coalesce equivalent repository refreshes, but must not satisfy a delivery from cache alone.

type ProjectionSnapshot ¶ added in v0.101.0

type ProjectionSnapshot struct {
	Repositories  []ProjectionDocument
	Organizations []ProjectionDocument
	LatestMerges  []LatestMerge
}

ProjectionSnapshot is the authoritative result of refreshing one GitHub App delivery. The reader owns GitHub access; the provider owns validation and the stable projection write order.

type ProjectionStore ¶ added in v0.100.0

type ProjectionStore interface {
	ListProjections(context.Context, Scope) ([]ProjectionDocument, error)
	GetProjection(context.Context, Scope, string) (ProjectionDocument, error)
	ListSeries(context.Context, Scope, string, string) (SeriesDocument, error)
	GetLeaderboard(context.Context, string) (LeaderboardDocument, error)
	ListPublicLatestMerges(context.Context, int) (PublicLatestMerges, error)
}

ProjectionStore is the narrow durable persistence adapter supplied by the host. Implementations map these operations to Firestore or another durable store; aggregation and disclosure stay in this package.

type ProjectionWriter ¶ added in v0.101.0

type ProjectionWriter interface {
	WriteRepositories(context.Context, string, []ProjectionDocument) error
	WriteOrganizations(context.Context, string, []ProjectionDocument) error
	WriteLatestMerges(context.Context, string, []LatestMerge) error
}

ProjectionWriter durably applies a complete authoritative snapshot. Every method is keyed by deliveryID and must be idempotent: a crash after a write and before DeliveryStore commits is safe to retry. Implementations should replace projections by ProjectionKey and replace the public merge view as a single logical operation.

type PublicEligibility ¶

type PublicEligibility struct {
	Repository string    `json:"repository" firestore:"repository"`
	READMEURL  string    `json:"readme_url" firestore:"readme_url"`
	VerifiedAt time.Time `json:"verified_at" firestore:"verified_at"`
}

PublicEligibility is the auditable root-README opt-in record required before a repository can appear in unauthenticated results. It is not inferred from GitHub repository visibility alone.

func VerifyPublicEligibility(repository, readmeURL, markdown string, verifiedAt time.Time) (PublicEligibility, error)

type PublicLatestMerges ¶ added in v0.100.0

type PublicLatestMerges struct {
	Entries []LatestMerge `json:"entries" firestore:"entries"`
}

type ReadModel ¶

type ReadModel interface {
	Dashboard(context.Context, Viewer) (Access[Dashboard], error)
	Stats(context.Context, Viewer, Scope, string) (Access[Stat], error)
	Series(context.Context, Viewer, Scope, string, string) (Access[Series], error)
	Leaderboard(context.Context, Viewer, string) (Access[Leaderboard], error)
	LatestMerges(context.Context, Viewer, int) (Access[[]LatestMerge], error)
}

ReadModel owns persistence and GitHub data projection. It must return only subjects whose public opt-in is recorded, unless the supplied viewer is an authenticated member of the private subject.

type Scope ¶

type Scope string

Scope identifies the GitHub subject represented by a statistic.

const (
	ScopeRepository   Scope = "repository"
	ScopeOrganization Scope = "organization"
	ScopeUser         Scope = "user"
)

type Series ¶

type Series struct {
	Scope  Scope         `json:"scope"`
	ID     string        `json:"id"`
	Metric string        `json:"metric"`
	Points []SeriesPoint `json:"points"`
}

Series is a named time-series for graph and table consumers.

type SeriesDocument ¶ added in v0.100.0

type SeriesDocument struct {
	Scope  Scope         `json:"scope" firestore:"scope"`
	ID     string        `json:"id" firestore:"id"`
	Metric string        `json:"metric" firestore:"metric"`
	Points []SeriesPoint `json:"points" firestore:"points"`
}

type SeriesPoint ¶

type SeriesPoint struct {
	At    time.Time `json:"at" firestore:"at"`
	Value int64     `json:"value" firestore:"value"`
}

SeriesPoint can render either a graph point or a table row.

type Service ¶

type Service struct {
	// Projector is the only supported webhook processor.
	Projector *ProjectionEngine
	ReadModel ReadModel
	Events    EventSource
}

Service applies disclosure policy around a Workbench read model and processes signed GitHub App webhook deliveries.

func (service Service) Dashboard(ctx context.Context, viewer Viewer) (Dashboard, error)

func (service Service) EventStream(ctx context.Context, viewer Viewer, filter EventFilter) ([]Event, <-chan Event, error)

func (service Service) LatestMerges(ctx context.Context, viewer Viewer, limit int) ([]LatestMerge, error)

func (service Service) Leaderboard(ctx context.Context, viewer Viewer, metric string) (Leaderboard, error)

func (service Service) ProcessWebhook(ctx context.Context, delivery WebhookDelivery, signature string) (bool, error)

func (service Service) Series(ctx context.Context, viewer Viewer, scope Scope, id, metric string) (Series, error)

func (service Service) Stats(ctx context.Context, viewer Viewer, scope Scope, id string) (Stat, error)

type Stat ¶

type Stat struct {
	Scope       Scope     `json:"scope"`
	ID          string    `json:"id"`
	DisplayName string    `json:"display_name"`
	Summary     Summary   `json:"summary"`
	UpdatedAt   time.Time `json:"updated_at"`
	Links       []Link    `json:"links,omitempty"`
}

Stat is one scoped repository, organization, or user result.

type StoreReadModel ¶ added in v0.100.0

type StoreReadModel struct {
	Store      ProjectionStore
	Membership MembershipResolver
}

func (model StoreReadModel) Dashboard(ctx context.Context, viewer Viewer) (Access[Dashboard], error)

func (model StoreReadModel) LatestMerges(ctx context.Context, viewer Viewer, limit int) (Access[[]LatestMerge], error)

func (model StoreReadModel) Leaderboard(ctx context.Context, viewer Viewer, metric string) (Access[Leaderboard], error)

func (model StoreReadModel) Series(ctx context.Context, viewer Viewer, scope Scope, id, metric string) (Access[Series], error)

func (model StoreReadModel) Stats(ctx context.Context, viewer Viewer, scope Scope, id string) (Access[Stat], error)

type Summary ¶

type Summary struct {
	Repositories int `json:"repositories" firestore:"repositories"`
	OpenPulls    int `json:"open_pulls" firestore:"open_pulls"`
	MergedPulls  int `json:"merged_pulls" firestore:"merged_pulls"`
	OpenIssues   int `json:"open_issues" firestore:"open_issues"`
	Releases     int `json:"releases" firestore:"releases"`
}

Summary is the compact dashboard card set.

type Viewer ¶

type Viewer struct {
	Authenticated bool
	Member        bool
	UserID        string
}

Viewer is resolved by the host before a private record is rendered.

type ViewerResolver ¶

type ViewerResolver interface {
	Viewer(*http.Request) (Viewer, error)
}

ViewerResolver binds the host authentication and membership system to the Workbench domain. The WB domain never accepts identity headers directly.

type Visibility ¶

type Visibility string

Visibility describes whether a response contains an explicitly opted-in public subject or a member-only private subject.

const (
	VisibilityPublic  Visibility = "public"
	VisibilityPrivate Visibility = "private"
)

type Wakeup ¶

type Wakeup struct {
	Key        string `json:"key" firestore:"key"`
	Repository string `json:"repository" firestore:"repository"`
	Event      string `json:"event" firestore:"event"`
}

Wakeup is a durable, coalescible unit of refresh work.

type WebhookDelivery ¶

type WebhookDelivery struct {
	ID         string
	Event      string
	Repository string
	Payload    []byte
}

WebhookDelivery is the verified, minimally parsed GitHub webhook envelope.