Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 68 additions & 26 deletions tooling/extension-bindings/IMPLEMENTATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ publication are outside the enabled Go workflows.

The binding implementation remains in `extensions`. The downstream common `rc`
executable belongs to `rc-cli` and will expose this implementation through a
thin adapter. Language-specific profilers remain independently implemented and
released programs.
thin library adapter. Language-specific profilers remain independently
implemented and released; the Go profiler also exposes a library API.

The following requirements apply throughout the pipeline:

Expand Down Expand Up @@ -716,9 +716,22 @@ rc bindings check
rc bindings update
```

The executable is built from `orchestrator/cmd/rc`. The reusable command
boundary is `orchestrator.Run(context.Context, []string, io.Writer, io.Writer)`;
it accepts the `bindings` command group and returns errors to its caller.
The standalone executable is built from `orchestrator/cmd/rc` and remains
supported independently of the common CLI. Its argument parser is
`orchestrator.Run(context.Context, []string, io.Writer, io.Writer)`.
It accepts the `bindings` command group and delegates to the library boundary:

```go
orchestrator.Execute(ctx, cwd, operation, options, stdout, stderr)
```

`Execute` accepts a context, an absolute working directory, an operation name,
typed `Options`, and non-nil output writers. It parses no command arguments and
does not change the process working directory. Initialize options using
`orchestrator.DefaultOptions()` to obtain the standalone native-tool defaults
from the current environment, then apply explicit overrides. Explicit empty
values are preserved. Relative input, output, override, and executable paths
resolve against the supplied directory; bare tool names retain PATH lookup.
The executable supplies process arguments and streams and chooses the exit code.

| Command | Behavior and output |
Expand Down Expand Up @@ -792,21 +805,48 @@ NOT maintain a second binding generator or duplicate compatibility rules.

### 13.2 Binding adapter and distribution

The reusable Go `orchestrator.Run` boundary and standalone command interface
provide integration boundaries. An adapter may invoke a versioned Go API or an
explicitly selected standalone tooling artifact, while preserving the command
contract defined here.

For an in-process adapter, the orchestrator, normalizer, and Go emitter modules
must be available as a resolvable, versioned dependency set. Relative `replace`
directives used for development inside `extensions` do not supply dependencies
to a downstream module. The schema bundle and required emitter resources must
also be located through an explicit installed tooling path.

For a subprocess adapter, invoke the selected binding tool with an argument
vector, preserve the caller's directory and streams, and propagate cancellation
and failure. Select its executable by an explicit managed path; dispatch MUST
NOT recursively resolve the common `rc` command as its own backend.
The common CLI MUST import the Go orchestrator and call `Execute` with typed
options from native Cobra commands. It MUST NOT rebuild an argument vector for
`Run` or dispatch to a separate `rc-bindings` executable. Generated SDKs under
`bindings/` are workload dependencies; the generator library lives under
`tooling/extension-bindings/orchestrator`.

The orchestrator, normalizer, and Go emitter modules must be available as a
resolvable, versioned dependency set. Relative `replace` directives used for
development inside `extensions` do not supply dependencies to a downstream
module. Installed schema and emitter resources must work outside a source
checkout. The common CLI integration will call exported Go normalization and
emission functions directly; Python tooling remains optional for Python targets.

Standalone generation in `extensions` MUST remain functional. Its entry point,
native-tool options, and ability to select an independently installed Go
profiler executable MUST remain supported. `Execute` preserves the existing
executable-based tooling and artifact identities as the default mode.

Library callers may set `Options.UseGoLibraries` to call `normalizer.Normalize`
and `goemitter.Emit` directly. `Normalizer` and `GoEmitter` must then be empty;
conflicting executable selections fail instead of being ignored. This option
does not change profiler selection: callers may use `LinkedGoProfiler` or retain
a standalone `GoProfiler` executable. Python emission remains external.

In library mode, normalizer and Go emitter identities retain their component
names and versions, with the SHA-256 of the actual host executable (`rc` when
integrated). No module checksum is substituted for an executable digest.
Rebuilding the host changes those identities and the normalized model digest.
Artifact locks must pin that host digest with the applicable component name and
version; a lock for a separately built normalizer or emitter fails. These checks
run before generation creates work files. Verification and regeneration use
the selected execution mode and retain the existing schema and identity checks.
Cancellation is checked around direct calls; the component APIs cannot interrupt
an active normalization or emission call. Schema resources are still required
through tooling discovery; packaging them for the common CLI is separate work.

Linked profiler support MUST be explicit and optional. Its identity must record
the actual linked module version and dependency checksum. Metadata schemas,
lock validation, and profiler schema consumers must support that identity before
new metadata is emitted. An executable SHA-256 and a module checksum identify
different artifacts; a linked identity MUST NOT satisfy an executable lock.
Explicit standalone profiler selection MUST retain executable identity checks.

The CLI integration must retain actual executing-tool provenance and all lock
checks. A separately installed CLI version is not a substitute for an emitter,
Expand All @@ -828,13 +868,15 @@ rc profile go generate <Go-profiler arguments>
rc profile python <Python-profiler arguments>
```

The common CLI's default installation includes the independently packaged Go
profiler. Other languages are optional profiler add-ons. Each profiler owns its
source parser, language runtime requirements, flags, and semantic validation.
The common CLI links the independently versioned Go profiler as a Go module.
Native Cobra commands bind typed options and invoke its exported functions;
default and explicit Go routes share the same command constructors. Go help and
flags use Cobra, including `--dir` and `--out`. Other languages are optional
profiler add-ons with their own source parsers and runtime requirements.

After selecting the profiler, the CLI forwards its argument vector without
translating language-specific options. Backend help and output remain owned by
the profiler. Launcher diagnostics must not contaminate profile data on stdout.
Optional profiler commands forward their argument vectors without translating
language-specific options. Their backend help and output remain owned by the
profiler. Launcher diagnostics must not contaminate profile data on stdout.

Interactive discovery may use managed installations, explicit configuration,
and `PATH`, subject to protocol compatibility checks. Binding verification and
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,25 @@ $defs:
name: {$ref: '#/$defs/nonEmptyString'}
version: {$ref: '#/$defs/nonEmptyString'}
sha256: {$ref: '#/$defs/sha256'}
profilerIdentity:
oneOf:
- {$ref: '#/$defs/toolIdentity'}
- {$ref: '#/$defs/linkedGoProfilerIdentity'}
linkedGoProfilerIdentity:
description: Exact linked Go profiler dependency, distinct from an executable digest.
type: object
additionalProperties: false
required: [kind, name, version, module, moduleSum]
properties:
kind: {const: go-module}
name: {const: go-rc-profiler}
version:
type: string
pattern: '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(\+incompatible)?$'
module: {const: github.com/runtimeconditions/go-rc-profiler}
moduleSum:
type: string
pattern: '^h1:[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$'
package:
description: >-
Matches the emitter target and runtimeconditions.bindings.yaml package.
Expand Down Expand Up @@ -256,7 +275,7 @@ $defs:
properties:
mode: {const: test-fixture}
fixtureAssembler: {$ref: '#/$defs/toolIdentity'}
profiler: {$ref: '#/$defs/toolIdentity'}
profiler: {$ref: '#/$defs/profilerIdentity'}
productionProvenance:
description: >-
Phase 5 and later committed package assembly. Source directory and tag
Expand All @@ -268,7 +287,7 @@ $defs:
properties:
mode: {const: production}
orchestrator: {$ref: '#/$defs/toolIdentity'}
profiler: {$ref: '#/$defs/toolIdentity'}
profiler: {$ref: '#/$defs/profilerIdentity'}
sourceDirectory:
type: string
pattern: '^bindings/[a-z0-9]+(?:-[a-z0-9]+)*/(go|python)$'
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,10 @@ title: Runtime Conditions toolchain lock
description: >-
Development may use workspace tools. A released lock pins normalizer,
orchestrator, emitters and independently installed profilers by version and
artifact SHA-256. Consumers must check that each selected language has both
an emitter and a profiler and that the actual artifacts match their digests.
artifact SHA-256. Go profiler pins may instead identify a linked module by
exact version and dependency checksum. Consumers must check that each selected
language has an emitter and profiler and that the selected identity form,
version and checksum match the lock without substituting another artifact kind.
type: object
additionalProperties: false
required: [apiVersion, kind, status]
Expand All @@ -22,7 +24,7 @@ properties:
normalizer: {$ref: '#/$defs/toolIdentity'}
orchestrator: {$ref: '#/$defs/toolIdentity'}
emitters: {$ref: '#/$defs/languageTools'}
profilers: {$ref: '#/$defs/languageTools'}
profilers: {$ref: '#/$defs/profilerTools'}
languages:
type: object
propertyNames:
Expand Down Expand Up @@ -64,6 +66,33 @@ $defs:
description: Optional retrieval URL for the exact checksummed released artifact.
type: string
pattern: '^https://[^\s]+$'
profilerIdentity:
oneOf:
- {$ref: '#/$defs/toolIdentity'}
- {$ref: '#/$defs/linkedGoProfilerIdentity'}
linkedGoProfilerIdentity:
description: Exact linked Go profiler dependency, distinct from an executable digest.
type: object
additionalProperties: false
required: [kind, name, version, module, moduleSum]
properties:
kind: {const: go-module}
name: {const: go-rc-profiler}
version:
type: string
pattern: '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(\+incompatible)?$'
module: {const: github.com/runtimeconditions/go-rc-profiler}
moduleSum:
type: string
pattern: '^h1:[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$'
profilerTools:
type: object
minProperties: 1
propertyNames:
pattern: '^[a-z][a-z0-9-]*$'
properties:
go: {$ref: '#/$defs/profilerIdentity'}
additionalProperties: {$ref: '#/$defs/toolIdentity'}
languageTools:
type: object
minProperties: 1
Expand Down
14 changes: 9 additions & 5 deletions tooling/extension-bindings/orchestrator/catalog.go
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,10 @@ type Toolchain struct {
Kind string `json:"kind" yaml:"kind"`
Status string `json:"status" yaml:"status"`
Tools struct {
Normalizer Tool `json:"normalizer" yaml:"normalizer"`
Orchestrator Tool `json:"orchestrator" yaml:"orchestrator"`
Emitters map[string]Tool `json:"emitters" yaml:"emitters"`
Profilers map[string]Tool `json:"profilers" yaml:"profilers"`
Normalizer Tool `json:"normalizer" yaml:"normalizer"`
Orchestrator Tool `json:"orchestrator" yaml:"orchestrator"`
Emitters map[string]Tool `json:"emitters" yaml:"emitters"`
Profilers map[string]ProfilerIdentity `json:"profilers" yaml:"profilers"`
} `json:"tools" yaml:"tools"`
Languages map[string]LanguageToolchain `json:"languages" yaml:"languages"`
Python struct {
Expand Down Expand Up @@ -178,9 +178,13 @@ func DiscoverProject(cwd, packagesPath, toolchainPath, toolingDirectory string)
return nil, fmt.Errorf("%s:%s: name is required by the %s native emitter", key, language, language)
}
if p.Toolchain.Status == "released" {
if p.Toolchain.Tools.Emitters[language].SHA256 == "" || p.Toolchain.Tools.Profilers[language].SHA256 == "" {
profiler, present := p.Toolchain.Tools.Profilers[language]
if p.Toolchain.Tools.Emitters[language].SHA256 == "" || !present {
return nil, fmt.Errorf("%s: released lock lacks emitter or profiler", language)
}
if err := profiler.Validate(); err != nil {
return nil, fmt.Errorf("%s: invalid released profiler lock: %w", language, err)
}
native, ok := p.Toolchain.Languages[language]
if !ok || native.LanguageVersion != target.LanguageVersion {
return nil, fmt.Errorf("%s:%s: exact language version differs from released lock", key, language)
Expand Down
Loading
Loading