Documentation
¶
Overview ¶
Package solution holds the host-side dispatch gate for the Solution executor contract. The Solution service binds a solution_method_policy to every RPC declaring its maximum network reach and state effect; the host reads that policy from the generated descriptors and refuses to dispatch any method whose declared ceiling exceeds the ceiling admitted for the current operation.
The gate constrains what the host chooses to invoke — it does not, and under this contract cannot, constrain what a solution executor actually does inside a handler. Unlike provider.proto (where ProviderHost brokers the provider's side effects and the host enforces the policy at the point of effect), the Solution contract has no host-brokered callback path: a plugin's real filesystem and registry writes are unmediated. Enforcing declared effects against plugin behavior would require a broker this contract does not define.
Two properties bound what the gate guarantees. First, it enforces caller-asserted intent, not authority: the constructors below stop a host from hand-widening its own bounds, but the ceiling is not bound to an authorized principal/operation/environment at a trusted chokepoint, so the gate prevents an honest host's accidental over-reach, not a hostile one's. Second, the tier vocabulary (Inspect/Scaffold/Render/Publish) is shaped by this contract alone: its fit to a host's real operations, and whether Render's reach stays REGISTRY_READ or becomes OFFLINE (which follows from how the host resolves the artifact — see solution.proto), are the consuming host's to establish.
Index ¶
- func EnforcingClientInterceptor() grpc.UnaryClientInterceptor
- type Ceiling
- type Client
- func (c *Client) Create(ctx context.Context, ceiling Ceiling, in *solutionv0.CreateRequest, ...) (*solutionv0.CreateResponse, error)
- func (c *Client) GetSolutionInformation(ctx context.Context, ceiling Ceiling, ...) (*solutionv0.GetSolutionInformationResponse, error)
- func (c *Client) Package(ctx context.Context, ceiling Ceiling, in *solutionv0.PackageRequest, ...) (*solutionv0.PackageResponse, error)
- func (c *Client) Render(ctx context.Context, ceiling Ceiling, in *solutionv0.RenderRequest, ...) (*solutionv0.RenderResponse, error)
- func (c *Client) Update(ctx context.Context, ceiling Ceiling, in *solutionv0.UpdateRequest, ...) (*solutionv0.UpdateResponse, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnforcingClientInterceptor ¶
func EnforcingClientInterceptor() grpc.UnaryClientInterceptor
EnforcingClientInterceptor is the host-side dispatch gate: a unary client interceptor installed on every agent connection (agents/manager.loader). For each outgoing Solution RPC it reads the declared policy and the ceiling stamped on the call context (see Client) and refuses to dispatch a call whose declared network or effect exceeds the admitted ceiling. Calls to services other than Solution pass through untouched, so installing it universally does not affect non-solution agents.
A call with no ceiling on its context is admitted against the least-privilege ceiling (CeilingInspect): a caller that never declared its operation may still read a solution executor's advertisement, but every mutating RPC is refused until the host declares a higher ceiling through Client. Defaulting to the minimum — rather than denying even the harmless read — keeps inspection ergonomic while staying fail-closed for every effectful RPC.
It covers unary RPCs only, which is complete because the Solution contract is unary-only — an invariant TestSolutionContractIsUnaryOnly guards. A streaming Solution RPC must not be added without a matching stream gate, or it would dispatch unchecked.
Types ¶
type Ceiling ¶
type Ceiling struct {
// contains filtered or unexported fields
}
Ceiling is the maximum network reach and state effect a host admits for one operation. A method is admitted only when both of its declared policy fields are at or below the ceiling.
The fields are unexported and a ceiling is obtained only through the named operation constructors below. That gives the ceiling an intent provenance: a caller declares the operation it is performing (inspect/scaffold/render/ publish) rather than hand-assembling bounds, so it cannot silently widen its own privilege with a struct literal, and the interceptor can never receive an incoherent ceiling (e.g. registry network with only read-only effect). The intent→ceiling mapping lives here as the single audited chokepoint. Binding that intent to an authorized principal is a separate concern the constructors do not address (see the package doc): the constructor proves which operation a caller named, not that the caller was entitled to it.
func CeilingInspect ¶
func CeilingInspect() Ceiling
CeilingInspect admits only offline, read-only RPCs — GetSolutionInformation. It is the ceiling for an operation that reads a solution executor's advertisement without invoking any lifecycle mutation.
func CeilingPublish ¶
func CeilingPublish() Ceiling
CeilingPublish admits every Solution RPC, including Package's registry push.
func CeilingRender ¶
func CeilingRender() Ceiling
CeilingRender admits Render — a registry pull of the packaged artifact plus a local-filesystem write of its manifests — and every lower RPC, but not Package's registry push.
func CeilingScaffold ¶
func CeilingScaffold() Ceiling
CeilingScaffold admits offline local-filesystem RPCs — Create and Update — but not Render (which pulls the packaged artifact) or Package's registry push.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the canonical host-side Solution client and the only path that can dispatch an effectful Solution RPC. It makes the operation ceiling a required argument of every call, so host code cannot dispatch a Solution RPC without declaring the operation it performs — the obligation is type-level, not a convention a caller can forget.
Each method checks the method's declared policy against the ceiling before it dispatches, so the guarantee is intrinsic to Client and does not depend on the connection having been dialed with EnforcingClientInterceptor: a Client built over a plain connection still refuses an over-ceiling call before the wire. It also stamps the ceiling onto the context so that interceptor — installed on every agent connection (agents/manager.Load) as defense in depth and to gate callers that bypass Client — admits the same call rather than defaulting it to least privilege.
The raw generated solutionv0.SolutionClient is deliberately not a second entry point for effectful calls: the context stamp is unexported (withCeiling), so a caller holding the raw client can only ever reach the least-privilege default ceiling — enough for the read-only advertisement, which stays reachable that way by design — while every mutating RPC fails closed. That leaves this type as the single path that can dispatch anything beyond that read.
func NewClient ¶
func NewClient(conn grpc.ClientConnInterface) *Client
NewClient wraps a connection with the typed, ceiling-enforcing Solution client. The connection need not carry EnforcingClientInterceptor — Client enforces the ceiling itself — though every agent connection from agents/manager.Load installs it anyway to gate any caller that reaches for the raw generated client.
func (*Client) Create ¶
func (c *Client) Create(ctx context.Context, ceiling Ceiling, in *solutionv0.CreateRequest, opts ...grpc.CallOption) (*solutionv0.CreateResponse, error)
Create scaffolds a new solution into a destination directory.
func (*Client) GetSolutionInformation ¶
func (c *Client) GetSolutionInformation(ctx context.Context, ceiling Ceiling, in *solutionv0.GetSolutionInformationRequest, opts ...grpc.CallOption) (*solutionv0.GetSolutionInformationResponse, error)
GetSolutionInformation reads a solution executor's advertisement.
func (*Client) Package ¶
func (c *Client) Package(ctx context.Context, ceiling Ceiling, in *solutionv0.PackageRequest, opts ...grpc.CallOption) (*solutionv0.PackageResponse, error)
Package builds an OCI artifact from a solution source directory and pushes it.
func (*Client) Render ¶
func (c *Client) Render(ctx context.Context, ceiling Ceiling, in *solutionv0.RenderRequest, opts ...grpc.CallOption) (*solutionv0.RenderResponse, error)
Render renders a packaged solution's manifests into a gitops destination.
func (*Client) Update ¶
func (c *Client) Update(ctx context.Context, ceiling Ceiling, in *solutionv0.UpdateRequest, opts ...grpc.CallOption) (*solutionv0.UpdateResponse, error)
Update reconciles an existing solution source with the executor's template.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package manifest defines the solution executor manifest: the schema that describes a codefly:solution plugin's identity, the services it scaffolds, the APIs and events it exposes and consumes, its UI extensions, its needs, its permissions, and the lifecycle operations it implements.
|
Package manifest defines the solution executor manifest: the schema that describes a codefly:solution plugin's identity, the services it scaffolds, the APIs and events it exposes and consumes, its UI extensions, its needs, its permissions, and the lifecycle operations it implements. |