Documentation
¶
Index ¶
- Constants
- func MapLabelMatchedIssue(issue *gh.Issue, owner, repo string) protocol.Event
- func MapPolledComment(comment *gh.IssueComment, owner, repo string) protocol.Event
- func MapPolledIssue(issue *gh.Issue, owner, repo string, lastSyncTime time.Time) protocol.Event
- func MapPolledPR(pr *gh.PullRequest, owner, repo string, lastSyncTime time.Time) protocol.Event
- func MapWebhookEvent(eventType string, payload []byte) (protocol.Event, bool)
- type Config
- type GitHubAgent
- type GitHubClient
- type GitHubConfig
- type NATSConfig
- type PollConfig
- type Poller
- type PollerConfig
- type RepoRef
- type SecurityConfig
- type WebhookConfig
- type WebhookServer
Constants ¶
const TestWebhookSecret = "test-webhook-secret" // #nosec G101 -- test-only constant, not a real credential
TestWebhookSecret is the HMAC secret used by NewTestAgent. Test code must sign webhook payloads with this value.
Variables ¶
This section is empty.
Functions ¶
func MapLabelMatchedIssue ¶ added in v0.0.6
MapLabelMatchedIssue converts a GitHub Issue found via label-filtered polling into a sekia Event with type "github.issue.matched".
func MapPolledComment ¶ added in v0.0.3
func MapPolledComment(comment *gh.IssueComment, owner, repo string) protocol.Event
MapPolledComment converts a GitHub IssueComment from the REST API into a sekia Event.
func MapPolledIssue ¶ added in v0.0.3
MapPolledIssue converts a GitHub Issue from the REST API into a sekia Event. Issues with CreatedAt after lastSyncTime are treated as newly opened; closed issues map to github.issue.closed; everything else is github.issue.updated.
func MapPolledPR ¶ added in v0.0.3
MapPolledPR converts a GitHub PullRequest from the REST API into a sekia Event. PRs with CreatedAt after lastSyncTime are treated as newly opened; merged PRs map to github.pr.merged; closed PRs to github.pr.closed; everything else is github.pr.updated.
func MapWebhookEvent ¶
MapWebhookEvent converts a GitHub webhook delivery into a sekia Event. eventType is the X-GitHub-Event header value. payload is the raw JSON body. Returns the event and true, or zero value and false if the event type/action is unsupported.
Types ¶
type Config ¶
type Config struct {
NATS NATSConfig `mapstructure:"nats"`
GitHub GitHubConfig `mapstructure:"github"`
Webhook WebhookConfig `mapstructure:"webhook"`
Poll PollConfig `mapstructure:"poll"`
Security SecurityConfig `mapstructure:"security"`
}
Config is the top-level GitHub agent configuration.
func LoadConfig ¶
LoadConfig reads configuration from file, env, and defaults.
type GitHubAgent ¶
type GitHubAgent struct {
// contains filtered or unexported fields
}
GitHubAgent bridges GitHub webhooks and/or REST API polling to the sekia event bus and executes GitHub API commands dispatched by workflows.
func NewAgent ¶
func NewAgent(cfg Config, logger zerolog.Logger) *GitHubAgent
NewAgent creates a GitHubAgent. Call Run() to start.
func NewTestAgent ¶
func NewTestAgent(natsURL string, natsOpts []nats.Option, ghBaseURL, webhookListen string, logger zerolog.Logger) *GitHubAgent
NewTestAgent creates a GitHubAgent configured for testing with a mock GitHub API and in-process NATS connection options.
func NewTestAgentWithPolling ¶ added in v0.0.3
func NewTestAgentWithPolling(natsURL string, natsOpts []nats.Option, ghClient GitHubClient, pollInterval time.Duration, repos []string, webhookListen string, logger zerolog.Logger) *GitHubAgent
NewTestAgentWithPolling creates a GitHubAgent configured for testing with polling enabled and an injected GitHubClient (for mock poll responses).
func (*GitHubAgent) Ready ¶
func (ga *GitHubAgent) Ready() <-chan struct{}
Ready returns a channel that is closed when the agent has finished starting.
func (*GitHubAgent) Run ¶
func (ga *GitHubAgent) Run() error
Run starts the agent: connects to NATS, subscribes to commands, starts the webhook server and/or poller, and blocks until signal or Stop().
func (*GitHubAgent) Stop ¶
func (ga *GitHubAgent) Stop()
Stop signals the agent to shut down. Safe to call from another goroutine.
func (*GitHubAgent) WebhookAddr ¶
func (ga *GitHubAgent) WebhookAddr() string
WebhookAddr returns the webhook server's listen address, or "" if not yet started.
type GitHubClient ¶
type GitHubClient interface {
// Command methods.
AddLabels(ctx context.Context, owner, repo string, number int, labels []string) error
RemoveLabel(ctx context.Context, owner, repo string, number int, label string) error
CreateComment(ctx context.Context, owner, repo string, number int, body string) error
EditIssueState(ctx context.Context, owner, repo string, number int, state string) error
// Polling methods — fetch a single page of results.
// Returns (items, nextPage, error). nextPage == 0 means no more data.
ListIssuesPage(ctx context.Context, owner, repo string, since time.Time, page, perPage int) ([]*gh.Issue, int, error)
ListPRsPage(ctx context.Context, owner, repo string, since time.Time, page, perPage int) ([]*gh.PullRequest, int, error)
ListCommentsPage(ctx context.Context, owner, repo string, since time.Time, page, perPage int) ([]*gh.IssueComment, int, error)
// Label-filtered polling — fetch issues by label and state (no time filter).
ListIssuesByLabelPage(ctx context.Context, owner, repo string, labels []string, state string, page, perPage int) ([]*gh.Issue, int, error)
}
GitHubClient abstracts the GitHub API methods used by commands and polling.
type GitHubConfig ¶
type GitHubConfig struct {
Token string `mapstructure:"token"`
}
GitHubConfig holds GitHub API settings.
type NATSConfig ¶
NATSConfig holds NATS connection settings.
type PollConfig ¶ added in v0.0.3
type PollConfig struct {
Enabled bool `mapstructure:"enabled"`
Interval time.Duration `mapstructure:"interval"`
Repos []string `mapstructure:"repos"`
PerTick int `mapstructure:"per_tick"`
Labels []string `mapstructure:"labels"`
State string `mapstructure:"state"`
}
PollConfig holds GitHub REST API polling settings.
type Poller ¶ added in v0.0.3
type Poller struct {
// contains filtered or unexported fields
}
Poller periodically queries the GitHub REST API for updated issues, PRs, and comments. Each tick fetches at most perTick items, resuming from where it left off via a cursor. When all items for all repos are consumed, it advances lastSyncTime and starts a new cycle.
When labels is non-empty, the poller operates in "label mode": it queries issues for each label separately (OR semantics — issues matching ANY label are returned), deduplicates across labels, only processes issues (skipping PRs and comments), and does not advance lastSyncTime.
func NewPoller ¶ added in v0.0.3
func NewPoller(cfg PollerConfig) *Poller
NewPoller creates a GitHub API poller.
type PollerConfig ¶ added in v0.0.6
type PollerConfig struct {
Client GitHubClient
Interval time.Duration
PerTick int
Repos []RepoRef
Labels []string
State string
OnEvent func(protocol.Event)
Logger zerolog.Logger
}
PollerConfig holds parameters for creating a Poller.
type RepoRef ¶ added in v0.0.3
RepoRef is a parsed owner/repo reference.
func ParseRepos ¶ added in v0.0.3
ParseRepos parses a slice of "owner/repo" strings into RepoRef values.
type SecurityConfig ¶ added in v0.0.8
type SecurityConfig struct {
CommandSecret string `mapstructure:"command_secret"`
}
SecurityConfig holds application-level security settings.
type WebhookConfig ¶
type WebhookConfig struct {
Listen string `mapstructure:"listen"`
Secret string `mapstructure:"secret"` // #nosec G117 -- config deserialization, not hardcoded
Path string `mapstructure:"path"`
}
WebhookConfig holds webhook HTTP server settings.
type WebhookServer ¶
type WebhookServer struct {
// contains filtered or unexported fields
}
WebhookServer receives GitHub webhook deliveries over HTTP.
func NewWebhookServer ¶
func NewWebhookServer(cfg WebhookConfig, onEvent func(protocol.Event), logger zerolog.Logger) *WebhookServer
NewWebhookServer creates a webhook server. onEvent is called for each mapped event.
func (*WebhookServer) Addr ¶
func (ws *WebhookServer) Addr() string
Addr returns the listener address. Only valid after Start is called.
func (*WebhookServer) Listen ¶
func (ws *WebhookServer) Listen() error
Listen binds the TCP socket. Call Serve() afterwards to accept connections.
func (*WebhookServer) Serve ¶
func (ws *WebhookServer) Serve() error
Serve accepts connections on the listener created by Listen. Blocks until shut down.
func (*WebhookServer) Shutdown ¶
func (ws *WebhookServer) Shutdown(ctx context.Context)
Shutdown gracefully stops the webhook server.
func (*WebhookServer) Start ¶
func (ws *WebhookServer) Start() error
Start binds and serves. It blocks until the server is shut down.