Documentation
¶
Overview ¶
Package deploy provides deployment state persistence for PromptKit arenas.
Index ¶
- Constants
- func AdapterBinaryName(provider string) string
- func ComputePackChecksum(data []byte) string
- type Action
- type AdapterClient
- func (c *AdapterClient) Apply(ctx context.Context, req *PlanRequest, callback ApplyCallback) (string, error)
- func (c *AdapterClient) Close() error
- func (c *AdapterClient) CompleteLogin(ctx context.Context, req *CompleteLoginRequest) (*CompleteLoginResponse, error)
- func (c *AdapterClient) Destroy(ctx context.Context, req *DestroyRequest, callback DestroyCallback) error
- func (c *AdapterClient) GetLoginURL(ctx context.Context, req *LoginURLRequest) (*LoginURLResponse, error)
- func (c *AdapterClient) GetProviderInfo(ctx context.Context) (*ProviderInfo, error)
- func (c *AdapterClient) Import(ctx context.Context, req *ImportRequest) (*ImportResponse, error)
- func (c *AdapterClient) Plan(ctx context.Context, req *PlanRequest) (*PlanResponse, error)
- func (c *AdapterClient) Status(ctx context.Context, req *StatusRequest) (*StatusResponse, error)
- func (c *AdapterClient) ValidateConfig(ctx context.Context, req *ValidateRequest) (*ValidateResponse, error)
- type AdapterManager
- type ApplyCallback
- type ApplyEvent
- type CompleteLoginRequest
- type CompleteLoginResponse
- type DestroyCallback
- type DestroyEvent
- type DestroyRequest
- type ImportRequest
- type ImportResponse
- type Locker
- type LoginProvider
- type LoginURLRequest
- type LoginURLResponse
- type PlanRequest
- type PlanResponse
- type Provider
- type ProviderInfo
- type ResourceChange
- type ResourceLink
- type ResourceResult
- type ResourceStatus
- type SavedPlan
- type State
- type StateStore
- type StatusRequest
- type StatusResponse
- type ValidateRequest
- type ValidateResponse
Constants ¶
const LoginCapability = "login"
LoginCapability is the ProviderInfo capability string an adapter advertises when it implements LoginProvider (browser-based autoconfigure).
Variables ¶
This section is empty.
Functions ¶
func AdapterBinaryName ¶
AdapterBinaryName returns the expected binary name for a provider.
func ComputePackChecksum ¶
ComputePackChecksum computes a sha256 checksum of pack data.
Types ¶
type AdapterClient ¶
type AdapterClient struct {
// contains filtered or unexported fields
}
AdapterClient launches an adapter binary and communicates with it via JSON-RPC 2.0 over stdio. It implements the Provider interface so callers can use it interchangeably with an in-process provider.
func NewAdapterClient
deprecated
func NewAdapterClient(binaryPath string) (*AdapterClient, error)
NewAdapterClient starts the adapter binary at the given path and returns a client ready for JSON-RPC calls. The process is kept alive for the lifetime of the client; call Close when done.
Deprecated: Use NewAdapterClientWithContext to pass a context that controls the subprocess lifetime.
func NewAdapterClientIO ¶
func NewAdapterClientIO(r io.Reader, w io.WriteCloser) *AdapterClient
NewAdapterClientIO creates an AdapterClient backed by the given reader and writer instead of a subprocess. Useful for testing.
func NewAdapterClientWithContext ¶ added in v1.3.10
func NewAdapterClientWithContext(ctx context.Context, binaryPath string) (*AdapterClient, error)
NewAdapterClientWithContext starts the adapter binary at the given path, using ctx to control the subprocess lifetime. If ctx is canceled, the subprocess is killed. Call Close when done.
func (*AdapterClient) Apply ¶
func (c *AdapterClient) Apply(ctx context.Context, req *PlanRequest, callback ApplyCallback) (string, error)
Apply executes the deployment. The adapter protocol returns all events in the final response rather than streaming them; this method replays those events to the callback (if non-nil) in order before returning. The returned string is the opaque adapter state.
func (*AdapterClient) Close ¶
func (c *AdapterClient) Close() error
Close shuts down the adapter process. It closes stdin (signaling EOF) and waits for the process to exit.
func (*AdapterClient) CompleteLogin ¶ added in v1.5.3
func (c *AdapterClient) CompleteLogin(ctx context.Context, req *CompleteLoginRequest) (*CompleteLoginResponse, error)
CompleteLogin hands the adapter the captured callback params and returns the resolved deploy profile and scoped token.
func (*AdapterClient) Destroy ¶
func (c *AdapterClient) Destroy(ctx context.Context, req *DestroyRequest, callback DestroyCallback) error
Destroy tears down the deployment.
func (*AdapterClient) GetLoginURL ¶ added in v1.5.3
func (c *AdapterClient) GetLoginURL(ctx context.Context, req *LoginURLRequest) (*LoginURLResponse, error)
GetLoginURL asks the adapter for the provider's browser authorize URL. A method-not-found error means the adapter does not implement login.
func (*AdapterClient) GetProviderInfo ¶
func (c *AdapterClient) GetProviderInfo(ctx context.Context) (*ProviderInfo, error)
GetProviderInfo returns metadata about the adapter.
func (*AdapterClient) Import ¶
func (c *AdapterClient) Import(ctx context.Context, req *ImportRequest) (*ImportResponse, error)
Import imports a pre-existing resource into the deployment state.
func (*AdapterClient) Plan ¶
func (c *AdapterClient) Plan(ctx context.Context, req *PlanRequest) (*PlanResponse, error)
Plan generates a deployment plan showing what would change.
func (*AdapterClient) Status ¶
func (c *AdapterClient) Status(ctx context.Context, req *StatusRequest) (*StatusResponse, error)
Status returns the current deployment status.
func (*AdapterClient) ValidateConfig ¶
func (c *AdapterClient) ValidateConfig(ctx context.Context, req *ValidateRequest) (*ValidateResponse, error)
ValidateConfig validates provider-specific configuration.
type AdapterManager ¶
type AdapterManager struct {
// contains filtered or unexported fields
}
AdapterManager discovers and manages deploy adapter binaries.
func NewAdapterManager ¶
func NewAdapterManager(projectDir string) *AdapterManager
NewAdapterManager creates a manager that searches for adapters relative to the given project directory.
func (*AdapterManager) Discover ¶
func (m *AdapterManager) Discover(provider string) (string, error)
Discover finds the adapter binary for the given provider. Search precedence:
- .promptarena/adapters/ (project-local)
- ~/.promptarena/adapters/ (user-level)
- $PATH (system-installed)
Returns the full path to the binary or an error if not found.
type ApplyCallback ¶
type ApplyCallback func(event *ApplyEvent) error
ApplyCallback is called for each ApplyEvent during Apply.
type ApplyEvent ¶
type ApplyEvent struct {
Type string `json:"type"` // "progress", "resource", "error", "complete"
Message string `json:"message,omitempty"`
Resource *ResourceResult `json:"resource,omitempty"`
}
ApplyEvent is a streaming event during Apply.
type CompleteLoginRequest ¶ added in v1.5.3
type CompleteLoginRequest struct {
Params map[string]string `json:"params"`
// Config is the current deploy config as JSON (may be partial or empty),
// carrying provider-specific coordinates the adapter needs to exchange the
// callback (e.g. the Omnia api_endpoint for the back-channel call).
Config string `json:"config,omitempty"`
}
CompleteLoginRequest hands the adapter the opaque query parameters captured from the browser's loopback callback (e.g. code, state). The adapter knows which it needs and how to exchange them.
type CompleteLoginResponse ¶ added in v1.5.3
type CompleteLoginResponse struct {
Profile map[string]interface{} `json:"profile"`
Token string `json:"token,omitempty"`
}
CompleteLoginResponse is the result of a completed login: the deploy profile to merge into the arena config (same shape as a dashboard-exported profile) and the scoped secret token to store outside the config file.
type DestroyCallback ¶
type DestroyCallback func(event *DestroyEvent) error
DestroyCallback is called for each DestroyEvent during Destroy.
type DestroyEvent ¶
type DestroyEvent struct {
Type string `json:"type"` // "progress", "resource", "error", "complete"
Message string `json:"message,omitempty"`
Resource *ResourceResult `json:"resource,omitempty"`
}
DestroyEvent is a streaming event during Destroy.
type DestroyRequest ¶
type DestroyRequest struct {
DeployConfig string `json:"deploy_config"`
Environment string `json:"environment,omitempty"`
PriorState string `json:"prior_state,omitempty"`
}
DestroyRequest is the input to Destroy.
type ImportRequest ¶
type ImportRequest struct {
ResourceType string `json:"resource_type"`
ResourceName string `json:"resource_name"`
Identifier string `json:"identifier"`
DeployConfig string `json:"deploy_config"`
Environment string `json:"environment,omitempty"`
PriorState string `json:"prior_state,omitempty"`
}
ImportRequest is the input to Import.
type ImportResponse ¶
type ImportResponse struct {
Resource ResourceStatus `json:"resource"`
State string `json:"state"`
}
ImportResponse is the output of Import.
type Locker ¶
type Locker struct {
// contains filtered or unexported fields
}
Locker provides file-based locking for deploy operations. It uses OS-level file locking to prevent concurrent deploys from different processes targeting the same project directory.
type LoginProvider ¶ added in v1.5.3
type LoginProvider interface {
GetLoginURL(ctx context.Context, req *LoginURLRequest) (*LoginURLResponse, error)
CompleteLogin(ctx context.Context, req *CompleteLoginRequest) (*CompleteLoginResponse, error)
}
LoginProvider is the OPTIONAL deploy capability for browser-based autoconfigure. Adapters that implement it advertise LoginCapability in ProviderInfo.Capabilities. The adaptersdk exposes get_login_url / complete_login only for providers that satisfy this interface, and the CLI degrades gracefully (method not found) for those that don't.
type LoginURLRequest ¶ added in v1.5.3
type LoginURLRequest struct {
CallbackURL string `json:"callback_url"`
State string `json:"state"`
// Config is the current deploy config as JSON (may be partial or empty). The
// adapter reads provider-specific coordinates from it — e.g. the Omnia
// adapter needs api_endpoint to build the authorize URL.
Config string `json:"config,omitempty"`
}
LoginURLRequest asks the adapter for the provider's authorize URL to open in the browser. The CLI supplies the loopback callback it is listening on and a CSRF state nonce.
type LoginURLResponse ¶ added in v1.5.3
type LoginURLResponse struct {
AuthorizeURL string `json:"authorize_url"`
}
LoginURLResponse carries the provider-specific authorize URL the CLI opens.
type PlanRequest ¶
type PlanRequest struct {
PackJSON string `json:"pack_json"`
DeployConfig string `json:"deploy_config"` // JSON provider config
ArenaConfig string `json:"arena_config,omitempty"` // JSON-serialized config.Config with loaded resources
Environment string `json:"environment,omitempty"`
PriorState string `json:"prior_state,omitempty"` // Opaque adapter state from last deploy
}
PlanRequest is the input to Plan.
type PlanResponse ¶
type PlanResponse struct {
Changes []ResourceChange `json:"changes"`
Summary string `json:"summary"`
// Warnings are non-blocking advisories surfaced to the user before the
// plan changes (e.g. a config that deploys but behaves surprisingly).
Warnings []string `json:"warnings,omitempty"`
}
PlanResponse is the output of Plan.
type Provider ¶
type Provider interface {
GetProviderInfo(ctx context.Context) (*ProviderInfo, error)
ValidateConfig(ctx context.Context, req *ValidateRequest) (*ValidateResponse, error)
Plan(ctx context.Context, req *PlanRequest) (*PlanResponse, error)
Apply(ctx context.Context, req *PlanRequest, callback ApplyCallback) (adapterState string, err error)
Destroy(ctx context.Context, req *DestroyRequest, callback DestroyCallback) error
Status(ctx context.Context, req *StatusRequest) (*StatusResponse, error)
Import(ctx context.Context, req *ImportRequest) (*ImportResponse, error)
}
Provider defines the interface that deploy adapters must implement.
type ProviderInfo ¶
type ProviderInfo struct {
Name string `json:"name"`
Version string `json:"version"`
Capabilities []string `json:"capabilities,omitempty"`
ConfigSchema string `json:"config_schema,omitempty"` // JSON Schema for provider config
}
ProviderInfo describes a deploy adapter's capabilities.
type ResourceChange ¶
type ResourceChange struct {
Type string `json:"type"` // Resource type (e.g., "agent_runtime", "a2a_endpoint")
Name string `json:"name"` // Resource name
Action Action `json:"action"` // CREATE, UPDATE, DELETE, NO_CHANGE
Detail string `json:"detail,omitempty"` // Human-readable description
}
ResourceChange describes a single resource modification.
type ResourceLink ¶ added in v1.5.9
type ResourceLink struct {
// Label is the short human-facing text for the link, e.g. "Console".
Label string `json:"label"`
// URL is the absolute URL to open. Adapters should include whatever scoping
// (workspace, namespace, project) the target needs in order to resolve for
// an operator with access to more than one.
URL string `json:"url"`
// Rel is an optional machine hint about what the link is, e.g. "console" or
// "logs". Clients may use it for an icon or ordering, but must still render
// links whose Rel they do not recognize.
Rel string `json:"rel,omitempty"`
}
ResourceLink is an optional operator-facing URL an adapter associates with a deployed resource — a web console, a logs view, a dashboard page.
The protocol contract, which both sides depend on:
- Optional end to end. An adapter that returns no links is fully supported and must never be treated as degraded. An absent field simply means "no links", so old adapters and new clients interoperate in both directions with no capability negotiation.
- Clients MUST NOT synthesize links. If the adapter returns none, the client shows nothing. Deriving a URL client-side bakes one provider's scheme into a provider-agnostic tool, and the control-plane host is not guaranteed to be the console host — so the guess is not even reliable for the provider it would be hardcoded for.
- Rel is a hint, not an enum to switch on. Render Label, open URL.
type ResourceResult ¶
type ResourceResult struct {
Type string `json:"type"`
Name string `json:"name"`
Action Action `json:"action"`
Status string `json:"status"` // "created", "updated", "deleted", "failed"
Detail string `json:"detail,omitempty"`
// Links are optional operator-facing URLs for this resource — see ResourceLink.
Links []ResourceLink `json:"links,omitempty"`
}
ResourceResult describes the outcome of a resource operation.
type ResourceStatus ¶
type ResourceStatus struct {
Type string `json:"type"`
Name string `json:"name"`
Status string `json:"status"` // "healthy", "unhealthy", "missing"
Detail string `json:"detail,omitempty"`
// Links are optional operator-facing URLs for this resource — see ResourceLink.
Links []ResourceLink `json:"links,omitempty"`
}
ResourceStatus describes the current state of a resource.
type SavedPlan ¶
type SavedPlan struct {
Version int `json:"version"`
CreatedAt string `json:"created_at"`
Provider string `json:"provider"`
Environment string `json:"environment"`
PackChecksum string `json:"pack_checksum"`
Plan *PlanResponse `json:"plan"`
Request *PlanRequest `json:"request"`
}
SavedPlan is a serialized deployment plan that can be applied later.
func NewSavedPlan ¶
func NewSavedPlan(provider, environment, packChecksum string, plan *PlanResponse, request *PlanRequest) *SavedPlan
NewSavedPlan creates a SavedPlan with current timestamp.
type State ¶
type State struct {
Version int `json:"version"`
Provider string `json:"provider"`
Environment string `json:"environment"`
LastDeployed string `json:"last_deployed"`
PackVersion string `json:"pack_version"`
PackChecksum string `json:"pack_checksum"`
AdapterVersion string `json:"adapter_version"`
LastRefreshed string `json:"last_refreshed,omitempty"`
State string `json:"state,omitempty"` // Opaque base64 adapter state
}
State represents the persisted deployment state.
type StateStore ¶
type StateStore struct {
// contains filtered or unexported fields
}
StateStore manages deploy state persistence.
func NewStateStore ¶
func NewStateStore(baseDir string) *StateStore
NewStateStore creates a StateStore rooted at the given directory.
func (*StateStore) DeletePlan ¶
func (s *StateStore) DeletePlan() error
DeletePlan removes the saved plan file. Returns nil if not found.
func (*StateStore) Load ¶
func (s *StateStore) Load() (*State, error)
Load reads the deploy state from disk. Returns nil, nil if the state file does not exist.
func (*StateStore) LoadPlan ¶
func (s *StateStore) LoadPlan() (*SavedPlan, error)
LoadPlan reads a saved plan from disk. Returns nil, nil if not found.
func (*StateStore) Save ¶
func (s *StateStore) Save(state *State) error
Save writes the deploy state to disk, creating directories as needed.
func (*StateStore) SavePlan ¶
func (s *StateStore) SavePlan(plan *SavedPlan) error
SavePlan persists a deployment plan to disk.
type StatusRequest ¶
type StatusRequest struct {
DeployConfig string `json:"deploy_config"`
Environment string `json:"environment,omitempty"`
PriorState string `json:"prior_state,omitempty"`
}
StatusRequest is the input to Status.
type StatusResponse ¶
type StatusResponse struct {
Status string `json:"status"` // "deployed", "not_deployed", "degraded", "unknown"
Resources []ResourceStatus `json:"resources,omitempty"`
State string `json:"state,omitempty"` // Opaque adapter state
// Links are optional deployment-wide operator-facing URLs that do not
// belong to any single resource — see ResourceLink.
Links []ResourceLink `json:"links,omitempty"`
}
StatusResponse describes the current deployment status.
type ValidateRequest ¶
type ValidateRequest struct {
Config string `json:"config"` // JSON provider config
}
ValidateRequest is the input to ValidateConfig.
type ValidateResponse ¶
type ValidateResponse struct {
Valid bool `json:"valid"`
Errors []string `json:"errors,omitempty"`
// Warnings are non-blocking advisories surfaced to the user. Unlike
// Errors, they do not make Valid false; the deployment proceeds.
Warnings []string `json:"warnings,omitempty"`
}
ValidateResponse is the output of ValidateConfig.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package adaptersdk provides a lightweight SDK for building deploy adapters.
|
Package adaptersdk provides a lightweight SDK for building deploy adapters. |