integrationpack

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Aug 29, 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 — docs/plans/signal-driven-review.md §6 ("Integration Pack")/§7 ("Service profile と service instance") and docs/plans/ signal-ingest-detailed-design.md §6 ("Config と Pack loader"), PR-4.

Scope (PR-4)

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 — that is PR-5's job (docs/plans/signal-ingest-detailed-design.md §5), which consumes this package'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 PR — see the PR-4 submission notes for why.

Contract (Pack contract v1)

docs/plans/signal-ingest-detailed-design.md §7 is the normative Pack contract every function/type here implements the boid-side half of:

  • ManifestAPIVersion fixes the manifest schema version this package understands (§7.3: boid never "前方互換を装う" — an unknown apiVersion is a hard load error, not a best-effort parse).
  • A service profile (ServiceProfile) declares only the SHAPE of a connection (credential slot names + injection method, whether an endpoint is configurable) — never a value (§7.1: "値 (endpoint 実値・ credential) を持たない"). 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 (docs/plans/signal-ingest-detailed-design.md §6.2's "先頭 slot を勝手に取るような縮退をしない") — both violations are hard LoadPacks errors, never a silent best-guess.

Core/Pack layering (Q16/Q17)

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 (boid-api-skills, evolving into the Pack repo — docs/plans/signal-driven-review.md §10's PR-8 note) and is never vendored into this one.

Index

Constants

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

ManifestAPIVersion is the only apiVersion ParseManifest accepts (docs/plans/signal-driven-review.md §6.3, docs/plans/ signal-ingest-detailed-design.md §7.3). A manifest declaring any other value — a typo, or a genuinely newer Pack contract version this binary predates — is rejected outright: the contract's own evolution rule (§7.3) states 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) docs/plans/signal-ingest-detailed-design.md §6.2 item 2 describes. 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 (docs/plans/ signal-ingest-detailed-design.md §6.2 item 3 — "起動エラー"):

  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 ("pack 不在").
  3. profile must be declared in that pack's manifest.
  4. the profile's endpoint requirement must match what sc provides: if Endpoint.Configurable, sc.Endpoint 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 — "endpoint 要求違反" covers both directions.
  5. the profile must declare exactly one credential slot, sc.Credentials must bind it ("slot 未 bind"), and must not carry any OTHER key ("未知 slot").
  6. (feat/credential-slot-instance-username) if that slot's injection is basic and it declares usernameFrom: instance, sc.Username must be non-empty and colon-free (RFC 7617 §2); if the slot does NOT declare usernameFrom: instance (a Pack-fixed username, or any non-basic injection), sc.Username must be empty — there is no slot for an instance-supplied value to fill.

The returned apigateway.ServiceConfig's AllowReadOnlyWrite is copied straight from sc.AllowReadOnlyWrite (F2, review finding, MEDIUM: an earlier version of this function silently dropped it, and its own doc comment here incorrectly claimed ServiceConfig had no such field for a uses: entry — config.ServiceConfig.AllowReadOnlyWrite lives on the exact same struct a uses: entry uses; the earlier bug was that this function never read it, not that it does not exist). 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 (PR-5 or a follow-up — see this package's doc.go for why that wiring is out of PR-4's own scope) — the interface PR-5 builds derived triggers and connector job wiring against.

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 (docs/plans/ signal-ingest-detailed-design.md §6.2 item 3 — "起動エラー").

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 — the v0 minimal JSON-Schema subset docs/plans/signal-ingest-detailed-design.md §6.2 item 4 specifies: "type/object/properties/required、値型は string/number/ boolean のみ". Hand-rolled rather than pulling in a real JSON Schema library — CLAUDE.md's "外部ライブラリは最小限" rule, and 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 (docs/plans/signal-ingest-detailed-design.md §6.2: "injection: bearer|basic|header|query"). AuthOAuth2 is deliberately absent: a Pack-declared OAuth2 profile remains a §12 open question in signal-driven-review.md, not something PR-4 implements.

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 — "仕様は profile、値は instance" (signal-driven-review.md
	// §7.1) applied to this one field.
	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 (still "仕様は profile、値は
	// instance", just applied the other way around from Username: here the
	// profile's "仕様" is merely "an instance-supplied username is
	// required"). 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 (docs/plans/signal-driven-review.md §6.3). 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 (docs/plans/signal-driven-review.md §6.3):

  • unknown fields at ANY depth are a hard error (yaml.Decoder. KnownFields(true) — docs/plans/signal-ingest-detailed-design.md §6.2 item 1: "未知 field はエラー (strict decode。黙って無視しない)")
  • apiVersion must equal ManifestAPIVersion, kind must equal ManifestKind
  • metadata.name/version are required
  • a service profile may declare at most one credential slot (§6.2's "先頭 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 (docs/plans/signal-ingest-detailed-design.md §6.2's
	// explicit v0 restriction).
	Version string
	// Dir is the absolute directory containing this Pack version's
	// integration.yaml — the bind-mount source PR-5's derived trigger uses
	// (docs/plans/signal-ingest-detailed-design.md §7.1 "mount 位置": Pack
	// 一式を /run/boid/integrations/<pack> へ read-only bind).
	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 (docs/plans/signal-ingest-detailed-design.md §6.2: "<ver> ディレクトリ名 が manifest の version と一致しない Pack は v0 では起動エラー" — the same "don't silently trust whichever is right" posture extends to name).

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 (docs/plans/ signal-ingest-detailed-design.md §6.1). 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: PR-4's "検証失敗 は起動エラー" posture (§6.2 item 3), 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 (docs/plans/signal-driven-review.md §6.4's `/opt/boid/integrations/<pack>/<version>/` tree), 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 — signal-ingest-detailed-design.md §6.2 item 4).
	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 (signal-driven-
	// review.md §7.1's "endpoint 固定のサービス (Slack) は configurable:
	// false + 既定値を宣言する" future extension is not implemented here) —
	// 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 (docs/plans/signal-ingest-detailed-design.md §6.2: "先頭
	// slot を勝手に取るような縮退をしない"). 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 — "接続の型" (§7.1): 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 (§7.1: "値 (endpoint 実値・credential) を持た ない") — 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