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
- func DesugarService(instanceName string, sc config.ServiceConfig, packs []*Pack) (apigateway.ServiceConfig, error)
- func ResolveServices(cfg *config.Config, packs []*Pack) ([]apigateway.ServiceConfig, error)
- func ValidSkillName(name string) bool
- type ConfigSchema
- type Connector
- type CredentialInjection
- type CredentialSlot
- type EndpointSpec
- type Manifest
- type ManifestMetadata
- type Pack
- type PropertySchema
- type ServiceProfile
- type Skill
Constants ¶
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.
const ManifestKind = "IntegrationPack"
ManifestKind is the only kind ParseManifest accepts.
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 — "起動エラー"):
- 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).
- pack/version must match an entry in packs ("pack 不在").
- profile must be declared in that pack's manifest.
- 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.
- the profile must declare exactly one credential slot, sc.Credentials must bind it ("slot 未 bind"), and must not carry any OTHER key ("未知 slot").
- (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 ¶
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 ¶
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 ¶
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 ¶
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.