hub

Documentation

Overview

Package hub is the daemon's client for the public Aileron discovery Hub (ADR-0013).

The Hub is a public GitHub repo at `aileron-hub` whose catalog holds three entry types, one YAML pointer per published artifact:

• `connectors/*.yaml` — community-published connectors, each pointing at the connector's canonical `github://OWNER/REPO` FQN.
• `actions/*.yaml` — published action templates, each pointing at the action's canonical `github://OWNER/REPO/actions/NAME` FQN and naming the connector it depends on.
• `suites/*.yaml` — published action suites, each enumerating its member action FQNs plus the derived `connectors_required` list.

Per #486, v0.x has no persisted cache and no `api.github.com` calls. Every Hub query shallow-clones the repo into a tmpdir, parses the entries for the requested directory, and discards the clone. A server-side metadata service that would re-introduce caching and popularity signals is tracked in #614.

Index

• Variables
• func Fingerprint(pub ed25519.PublicKey) string
• func PublisherFootprint(entries []ConnectorEntry, e ConnectorEntry) []string
• type ActionEntry
  • func FilterActionsByKeyword(entries []ActionEntry, q string) []ActionEntry
• type Client
  • func (c *Client) FetchActionByFQN(ctx context.Context, fqn string) (ActionEntry, error)
  • func (c *Client) FetchAllActions(ctx context.Context) ([]ActionEntry, error)
  • func (c *Client) FetchAllConnectors(ctx context.Context) ([]ConnectorEntry, error)
  • func (c *Client) FetchAllSuites(ctx context.Context) ([]SuiteEntry, error)
  • func (c *Client) FetchConnectorByFQN(ctx context.Context, fqn string) (ConnectorEntry, error)
  • func (c *Client) FetchPublisherKey(ctx context.Context, keyURL string) (ed25519.PublicKey, string, error)
  • func (c *Client) FetchSuiteByFQN(ctx context.Context, fqn string) (SuiteEntry, error)
• type ConnectorEntry
  • func FilterConnectorsByKeyword(entries []ConnectorEntry, q string) []ConnectorEntry
• type SuiteEntry
  • func FilterSuitesByKeyword(entries []SuiteEntry, q string) []SuiteEntry

Variables

var ErrNotFound = errors.New("hub: entry not found")

ErrNotFound signals that a requested FQN has no matching Hub entry in the requested catalog (connectors, actions, or suites).

Functions

func Fingerprint

func Fingerprint(pub ed25519.PublicKey) string

Fingerprint formats a key's SHA-256 hash to match the `aileron keyring trust` output: `sha256:<22 chars base64-no-padding>`. Long enough to disambiguate keys at a glance, short enough to fit on a terminal line. Same shape as the canonical ssh-keygen idioms.

func PublisherFootprint

func PublisherFootprint(entries []ConnectorEntry, e ConnectorEntry) []string

PublisherFootprint returns the FQNs of every connector entry by the same publisher as the supplied entry, excluding the entry's own FQN. Used to surface "publisher's other connectors" context in the install-decision payload (#487). Trust-state semantics are connector-scoped, so this helper stays connector-typed.

Types

type ActionEntry

type ActionEntry struct {
	FQN             string   `yaml:"fqn" json:"fqn"`
	Description     string   `yaml:"description" json:"description"`
	PublisherGithub string   `yaml:"publisher_github" json:"publisher_github"`
	ConnectorFQN    string   `yaml:"connector_fqn" json:"connector_fqn"`
	Intents         []string `yaml:"intents,omitempty" json:"intents,omitempty"`
	Category        string   `yaml:"category,omitempty" json:"category,omitempty"`
}

ActionEntry is one Hub action-template listing. Matches the YAML files committed to `aileron-hub/actions/*.yaml`. Action entries are discovery metadata; the canonical action template (TOML frontmatter + Markdown body per ADR-0003) is fetched from the publisher's repo at install time, not from the Hub.

func FilterActionsByKeyword

func FilterActionsByKeyword(entries []ActionEntry, q string) []ActionEntry

FilterActionsByKeyword returns the subset of action entries whose FQN or description contains q (substring, case-insensitive). Empty q returns all entries.

type Client

type Client struct {
	// URL is a git-clonable Hub URL. file://, https://, and ssh URLs
	// all work — useful for tests that point at a local fixture repo.
	URL string

	// HTTP is used for fetching publisher key bytes from `key_url`.
	// nil means use http.DefaultClient.
	HTTP *http.Client

	// CloneTimeout bounds the shallow-clone subprocess. Zero means
	// 30 seconds.
	CloneTimeout time.Duration
}

Client fetches entries from a configured Hub git URL.

Concurrent calls are safe: each Fetch* shallow-clones into its own tmpdir.

func (*Client) FetchActionByFQN

func (c *Client) FetchActionByFQN(ctx context.Context, fqn string) (ActionEntry, error)

FetchActionByFQN returns the action entry whose FQN matches exactly, or ErrNotFound.

func (*Client) FetchAllActions

func (c *Client) FetchAllActions(ctx context.Context) ([]ActionEntry, error)

FetchAllActions shallow-clones the Hub repo, parses every YAML file under `actions/`, and returns the entries sorted by FQN.

func (*Client) FetchAllConnectors

func (c *Client) FetchAllConnectors(ctx context.Context) ([]ConnectorEntry, error)

FetchAllConnectors shallow-clones the Hub repo, parses every YAML file under `connectors/`, and returns the entries sorted by FQN. The clone directory is deleted before return.

A failed clone (network down, URL wrong, repo missing) returns a wrapped error suitable for surfacing as 503 Hub-unreachable.

func (*Client) FetchAllSuites

func (c *Client) FetchAllSuites(ctx context.Context) ([]SuiteEntry, error)

FetchAllSuites shallow-clones the Hub repo, parses every YAML file under `suites/`, and returns the entries sorted by FQN.

func (*Client) FetchConnectorByFQN

func (c *Client) FetchConnectorByFQN(ctx context.Context, fqn string) (ConnectorEntry, error)

FetchConnectorByFQN returns the connector entry whose FQN matches exactly, or ErrNotFound.

func (*Client) FetchPublisherKey

func (c *Client) FetchPublisherKey(ctx context.Context, keyURL string) (ed25519.PublicKey, string, error)

FetchPublisherKey downloads the PEM-encoded ed25519 public key at keyURL and returns the parsed key plus its fingerprint string. The fingerprint format matches `aileron keyring trust` output: `sha256:<base64-no-padding, first 22 chars>`.

func (*Client) FetchSuiteByFQN

func (c *Client) FetchSuiteByFQN(ctx context.Context, fqn string) (SuiteEntry, error)

FetchSuiteByFQN returns the suite entry whose FQN matches exactly, or ErrNotFound.

type ConnectorEntry

type ConnectorEntry struct {
	FQN             string `yaml:"fqn" json:"fqn"`
	Description     string `yaml:"description" json:"description"`
	PublisherGithub string `yaml:"publisher_github" json:"publisher_github"`
	KeyURL          string `yaml:"key_url" json:"key_url"`
	ReleasePattern  string `yaml:"release_pattern" json:"release_pattern"`
}

ConnectorEntry is one Hub connector listing. Matches the YAML files committed to `aileron-hub/connectors/*.yaml`. Field tags align with both the YAML files and the OpenAPI `HubConnectorEntry` schema.

func FilterConnectorsByKeyword

func FilterConnectorsByKeyword(entries []ConnectorEntry, q string) []ConnectorEntry

FilterConnectorsByKeyword returns the subset of entries whose FQN or description contains q (substring, case-insensitive). An empty q returns all entries.

type SuiteEntry

type SuiteEntry struct {
	FQN                string   `yaml:"fqn" json:"fqn"`
	Description        string   `yaml:"description" json:"description"`
	PublisherGithub    string   `yaml:"publisher_github" json:"publisher_github"`
	MemberActions      []string `yaml:"member_actions" json:"member_actions"`
	ConnectorsRequired []string `yaml:"connectors_required,omitempty" json:"connectors_required,omitempty"`
	Category           string   `yaml:"category,omitempty" json:"category,omitempty"`
}

SuiteEntry is one Hub action-suite listing. Matches the YAML files committed to `aileron-hub/suites/*.yaml`. A suite entry names its member actions and the connectors those actions transitively require. The authoritative `suite.toml` (per #564) still lives in the publisher's repo; the Hub entry is the discovery pointer.

func FilterSuitesByKeyword

func FilterSuitesByKeyword(entries []SuiteEntry, q string) []SuiteEntry

FilterSuitesByKeyword returns the subset of suite entries whose FQN or description contains q (substring, case-insensitive). Empty q returns all entries.