integrationpack

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 18, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package integrationpack implements the Integration Pack manifest schema, loader, and "脱糖" (desugaring) that turns a services.<name>.uses reference into the apigateway.ServiceConfig the API gateway already understands.

Scope

This package is deliberately narrow: manifest parsing/validation (manifest.go), directory enumeration (pack.go), the v0 minimal JSON-Schema subset a connector's declared config is checked against (configschema.go), and the profile→apigateway.ServiceConfig desugaring (resolve.go). It does NOT generate derived triggers, execute connectors, or mount Pack skills into a job sandbox — a later package consumes this one's *Pack/Manifest/DesugarService/ResolveServices as its foundation. Wiring LoadPacks+ResolveServices into the live daemon startup path (internal/server/wire.go's gateway wiring point) is also left to that follow-up.

Contract (Pack contract v1)

Every function/type here implements the boid-side half of the Pack contract:

  • ManifestAPIVersion fixes the manifest schema version this package understands — an unknown apiVersion is a hard load error, not a best-effort parse (boid never pretends forward compatibility).
  • A service profile (ServiceProfile) declares only the SHAPE of a connection (credential slot names + injection method, whether an endpoint is configurable) — never a value. Values live in config.yaml's services.<name> entry (a "service instance") and are bound by DesugarService.
  • v0 restricts a profile to AT MOST one credential slot and requires the installed <version> directory name to match the manifest's own metadata.version exactly — both violations are hard LoadPacks errors, never a silent best-guess.

Core/Pack layering

No file in this package imports anything service-specific (Jira/Slack/ Bitbucket-...) — see TestQ16_NoServiceSpecificImports — and this package adds no database schema at all (it has no internal/db dependency; a loaded Pack registry lives only in daemon process memory, rebuilt from disk on every restart). Official Pack content (connectors/skills/ resolvers) lives in a separate repo and is never vendored into this one.

Index

Constants

View Source
const ManifestAPIVersion = "boid.dev/v1"

ManifestAPIVersion is the only apiVersion ParseManifest accepts. A manifest declaring any other value — a typo, or a genuinely newer Pack contract version this binary predates — is rejected outright: boid never pretends forward compatibility with a Pack contract version it does not implement.

View Source
const ManifestKind = "IntegrationPack"

ManifestKind is the only kind ParseManifest accepts.

View Source
const UsernameFromInstance = "instance"

UsernameFromInstance is the only value CredentialSlot.UsernameFrom currently recognizes — see that field's own doc comment.

Variables

This section is empty.

Functions

func DesugarService

func DesugarService(instanceName string, sc config.ServiceConfig, packs []*Pack) (apigateway.ServiceConfig, error)

DesugarService resolves one services.<name> config entry — sc.Uses must be non-empty — against packs, producing the apigateway.ServiceConfig the gateway registry sees for it (the "脱糖", desugaring, of a uses: reference). instanceName becomes the returned ServiceConfig's Name (and appears in every error message this function returns).

Resolution order, each step a hard error naming instanceName:

  1. sc.Uses parses as "<pack>/<profile>@<version>" (config. ParseUsesReference — already checked once at config-load time by config.validateServiceConfig; re-checked here since this function may be called with a hand-built config.ServiceConfig that skipped that validation, e.g. in a test).
  2. pack/version must match an entry in packs.
  3. profile must be declared in that pack's manifest.
  4. sc.Endpoint and sc.EndpointSecretKey must not both be set (mutually exclusive, the same "already checked once at config-load time, re-checked here" posture item 1 above has). The profile's endpoint requirement must then match what sc provides: if Endpoint.Configurable, at least one of sc.Endpoint/sc.EndpointSecretKey must be non-empty; otherwise v0 has no Pack-declared default endpoint to fall back to (see ServiceProfile.Endpoint's own doc comment), so ANY use of such a profile is rejected in v0.
  5. the profile must declare exactly one credential slot, sc.Credentials must bind it, and must not carry any other key.
  6. sc.Username and sc.UsernameSecretKey must not both be set. If that slot's injection is basic and it declares usernameFrom: instance, exactly one of sc.Username (non-empty and colon-free, RFC 7617 §2, checked here) or sc.UsernameSecretKey (colon-checked later instead, at request time, once the secret store resolves it) must be set; if the slot does NOT declare usernameFrom: instance (a Pack-fixed username, or any non-basic injection), neither may be set — there is no slot for an instance-supplied value to fill.

The returned apigateway.ServiceConfig's AllowReadOnlyWrite is copied straight from sc.AllowReadOnlyWrite: a Pack-profile-backed instance opts into the read-only→GET/HEAD-only gate exactly the same way a free-form base_url/auth entry does via config.APIGatewayServices().

func ResolveServices

func ResolveServices(cfg *config.Config, packs []*Pack) ([]apigateway.ServiceConfig, error)

ResolveServices returns the full flat []apigateway.ServiceConfig list for cfg.Services: free-form entries (base_url/auth) pass through cfg.APIGatewayServices() unchanged, and uses: entries (config. Config.UsesServices()) are desugared against packs via DesugarService. This is the single function internal/server/wire.go's gateway wiring point should call in place of cfg.APIGatewayServices() alone, once wired.

Unlike APIGatewayServices() (which silently skips an entry that fails its own, unrelated validation — see that method's "already validated by Config.UnmarshalYAML" invariant), a uses: entry that fails to desugar FAILS ResolveServices as a whole: an unresolvable Pack reference is an installation/config error the daemon should refuse to start with, not a service quietly missing from the registry.

func ValidSkillName

func ValidSkillName(name string) bool

ValidSkillName reports whether name matches skills[].name's allowlist — exported so a consumer of already-loaded Packs (internal/dispatcher's skillLinks, which turns Skill.Name into a <discovery root>/<Name> symlink basename) can apply the SAME check as defense in depth, rather than reimplementing a second, potentially-divergent one. ParseManifest is the primary gate (a manifest failing this fails daemon startup outright); this export exists for the consumer that cannot assume every *Pack it is ever handed came through ParseManifest (a test fixture, a future constructor).

Types

type ConfigSchema

type ConfigSchema struct {
	// Type is always "object" for a schema parseConfigSchema produced (v0
	// supports no other root type) — kept as a field (rather than assumed)
	// so a hand-built ConfigSchema in a test can still be introspected.
	Type string
	// Properties maps each declared property name to its (string/number/
	// boolean) leaf type. A property not listed here is NOT rejected by
	// Validate — v0 does not implement JSON Schema's additionalProperties:
	// false; see Validate's own doc comment.
	Properties map[string]PropertySchema
	// Required lists property names that must be present in a validated
	// value. Every entry is guaranteed (by parseConfigSchema) to also
	// appear in Properties.
	Required []string
}

ConfigSchema is a connector's declared configSchema — a v0 minimal JSON-Schema subset ("type/object/properties/required", leaf value types string/number/boolean only). Hand-rolled rather than pulling in a real JSON Schema library: the subset this package needs is narrow enough that a full implementation (refs, oneOf/anyOf, format, ...) would be pure unused surface. Constructed by parseConfigSchema (manifest.go), which already validates the schema document ITSELF (root type, property types, required references) — this type's own Validate method checks a candidate VALUE against an already-valid schema.

func (ConfigSchema) Validate

func (s ConfigSchema) Validate(value map[string]any) error

Validate checks value — a connector config already decoded from JSON/YAML into Go's generic any shapes (map[string]any, with string/bool/float64/ int/int64 leaves) — against s:

  • every name in s.Required must be present in value
  • for every key in value that ALSO appears in s.Properties, the value's Go type must match the declared leaf type (string→string, boolean→bool, number→any of int/int32/int64/float32/float64 — both yaml.v3's and encoding/json's own decoded numeric shapes are accepted, since callers may come from either)
  • a key in value with NO corresponding s.Properties entry is NOT an error — v0 does not implement JSON Schema's additionalProperties: false (deliberately out of scope; see this type's own doc comment)

A nil value is treated as an empty object — Validate then only fails if s.Required is non-empty.

type Connector

type Connector struct {
	Name           string
	Executable     string
	ServiceProfile string
	// ConfigSchema validates a connector's declared config (§6.2 item 4).
	// nil means the connector takes no config at all.
	ConfigSchema *ConfigSchema
}

Connector is one connectors[] entry.

type CredentialInjection

type CredentialInjection string

CredentialInjection selects how a service profile's credential slot is injected into a proxied request — a v0 subset of apigateway.AuthKind (bearer|basic|header|query). AuthOAuth2 is deliberately absent: a Pack-declared OAuth2 profile is not implemented in v0.

const (
	InjectionBearer CredentialInjection = "bearer"
	InjectionBasic  CredentialInjection = "basic"
	InjectionHeader CredentialInjection = "header"
	InjectionQuery  CredentialInjection = "query"
)

type CredentialSlot

type CredentialSlot struct {
	Name      string
	Injection CredentialInjection
	// Header is the header name to set — required (and only meaningful)
	// when Injection == InjectionHeader, mirroring config.ServiceAuthConfig.Header.
	Header string
	// Query is the query parameter name to set — required (and only
	// meaningful) when Injection == InjectionQuery, mirroring
	// config.ServiceAuthConfig.Query.
	Query string
	// Username is the fixed Basic-auth username half — meaningful only when
	// Injection == InjectionBasic, and mutually exclusive with
	// UsernameFrom (exactly one of the two is required for a basic slot).
	// Declared on the SLOT, not the instance: RFC 7617 usernames for a
	// token-as-password convention (e.g. Bitbucket's
	// "x-bitbucket-api-token-auth") are a property of the API itself, which
	// the Pack author knows and an operator should never have to supply per
	// instance.
	Username string
	// UsernameFrom selects the Basic-auth username SOURCE when Injection ==
	// InjectionBasic: the zero value ("") means Username above supplies a
	// Pack-fixed value (the Bitbucket case); the only other recognized
	// value, UsernameFromInstance ("instance"), means the username is
	// INSTANCE-SPECIFIC — the Pack only declares THAT an instance must
	// supply one, not the value itself. This is what Jira Cloud's Basic-auth
	// convention needs (username = the operator's own Atlassian account
	// email, which differs per instance and so cannot be a fixed manifest
	// constant the way Bitbucket's convention is). Mutually exclusive with
	// Username; DesugarService is where the instance's actual value
	// (config.ServiceConfig.Username) gets bound in. Meaningless (and
	// rejected by parseCredentialSlot) for any injection other than basic.
	UsernameFrom string
}

CredentialSlot is one profile credential slot declaration.

type EndpointSpec

type EndpointSpec struct {
	// Configurable, when true, means an instance MUST supply Endpoint
	// (DesugarService rejects a uses: entry that omits it). When false (the
	// zero value — also what an omitted endpoint: block means), an instance
	// must NOT supply one — v0 has no default-endpoint mechanism to fall
	// back to, so DesugarService rejects any use of such a profile
	// altogether (see its own doc comment for the full reasoning).
	Configurable bool
}

EndpointSpec is a service profile's endpoint.

type Manifest

type Manifest struct {
	APIVersion      string
	Kind            string
	Metadata        ManifestMetadata
	ServiceProfiles []ServiceProfile
	Connectors      []Connector
	Skills          []Skill
}

Manifest is one Pack's strict-decoded, structurally-validated integration.yaml. Produced by ParseManifest; LoadPacks (pack.go) additionally cross-checks Metadata against the directory it was installed under.

func ParseManifest

func ParseManifest(data []byte) (*Manifest, error)

ParseManifest strict-decodes and structurally validates one integration.yaml document:

  • unknown fields at ANY depth are a hard error (yaml.Decoder. KnownFields(true) — strict decode, never silently ignored)
  • apiVersion must equal ManifestAPIVersion, kind must equal ManifestKind
  • metadata.name/version are required
  • a service profile may declare at most one credential slot (more than one is a hard error, not a silently-take-the-first fallback)
  • each credential slot's injection is one of bearer/basic/header/query, with its injection-conditional field (header/query/username, or for basic: exactly one of username/usernameFrom) required
  • connectors[].serviceProfile and skills[].requiresServiceProfile must each name a serviceProfiles[] entry declared in the SAME manifest
  • a connector's configSchema, if present, is itself validated against the v0 subset (root type must be "object", every property type one of string/number/boolean, required[] only names declared properties)

ParseManifest does NOT check Metadata against an installation directory — LoadPacks (pack.go) does that, since only it knows the directory a manifest was found under.

type ManifestMetadata

type ManifestMetadata struct {
	Name    string
	Version string
}

ManifestMetadata is the manifest's metadata: block.

type Pack

type Pack struct {
	// Name is the manifest's own metadata.name — LoadPacks has already
	// checked this equals the <pack> directory segment it was found under.
	Name string
	// Version is the manifest's own metadata.version — LoadPacks has
	// already checked this equals the <version> directory segment it was
	// found under (an explicit v0 restriction).
	Version string
	// Dir is the absolute directory containing this Pack version's
	// integration.yaml — the bind-mount source a derived trigger uses to
	// mount the Pack read-only into a job sandbox.
	Dir string
	// Manifest is this Pack's fully parsed, structurally-validated
	// integration.yaml content.
	Manifest Manifest
}

Pack is one loaded, validated <dir>/<pack>/<version>/integration.yaml — LoadPacks' unit of enumeration.

func LoadPacks

func LoadPacks(dir string) ([]*Pack, error)

LoadPacks enumerates <dir>/<pack-name>/<version>/integration.yaml, strict-decoding and validating each manifest found (ParseManifest), and additionally checking that the manifest's own metadata.name/ metadata.version agree with the directory it was installed under — a mismatch in either direction is a v0 startup error, never silently trusted.

dir not existing at all is NOT an error — it returns (nil, nil), the same as an empty dir: the default integrations.dir (/opt/boid/integrations) will not exist on a deployment with no Packs installed yet, and that is not a misconfiguration. Every OTHER failure — a version directory with no integration.yaml at all, a manifest that fails ParseManifest, a name/version mismatch against the installation directory — IS a hard error naming the offending path, matching how config.yaml's own services: entries fail config.Load() loudly rather than being skipped.

dir's own immediate children that are not directories (e.g. a stray README.md) are skipped; the expected layout is a curated directory containing ONLY Pack subdirectories (`/opt/boid/integrations/<pack>/ <version>/`), not an arbitrary repo checkout root.

func (*Pack) ServiceProfile

func (p *Pack) ServiceProfile(name string) (*ServiceProfile, bool)

ServiceProfile finds the named service profile within p.Manifest, or (nil, false) if p declares no profile with that name — the lookup DesugarService (resolve.go) uses to resolve a uses: reference's profile half.

type PropertySchema

type PropertySchema struct {
	// Type is one of "string", "number", "boolean" (v0's supported leaf types).
	Type string
}

PropertySchema is one ConfigSchema.Properties entry's leaf type.

type ServiceProfile

type ServiceProfile struct {
	Name string
	// Endpoint declares whether an instance may/must supply an endpoint
	// value. v0 has no Pack-declared DEFAULT endpoint field — see
	// DesugarService's own doc comment for the resulting v0 limitation.
	Endpoint EndpointSpec
	// Credentials is the profile's declared credential slot(s). v0 requires
	// AT MOST one — LoadPacks rejects a profile declaring more than one
	// outright (no silent take-the-first fallback). Zero slots is
	// structurally allowed (an unauthenticated public API profile), but
	// DesugarService has nothing to bind for such a profile in v0 — see its
	// own doc comment.
	Credentials []CredentialSlot
}

ServiceProfile is one serviceProfiles[] entry: the credential slot(s) and endpoint requirement a service instance (config.yaml services.<name>) must satisfy to use this profile. Never carries a value of its own — see DesugarService for where instance values get bound.

type Skill

type Skill struct {
	Name string
	Path string
	// RequiresServiceProfile, when non-empty, must name a ServiceProfiles[]
	// entry declared in the same manifest — mirrors Connector.ServiceProfile.
	RequiresServiceProfile string
}

Skill is one skills[] entry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL