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 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 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"`
}
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"`
}
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
}
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. |