Documentation
¶
Overview ¶
Package api provides Forge-style HTTP handlers and middleware for the ctrlplane REST API. It supports both standalone operation via Handler() and Forge extension integration via RegisterRoutes() with full OpenAPI metadata generation.
Index ¶
- type API
- type AddDomainAPIRequest
- type AddRouteAPIRequest
- type CancelDeploymentRequest
- type ConfigureHealthCheckAPIRequest
- type CreateInstanceRequest
- type CreateTenantAPIRequest
- type DeleteInstanceRequest
- type DeleteSecretRequest
- type DeployAPIRequest
- type EmptyRequest
- type GetDeploymentRequest
- type GetInstanceHealthRequest
- type GetInstanceRequest
- type GetReleaseRequest
- type InstanceActionRequest
- type InstanceTelemetryRequest
- type ListDeploymentsRequest
- type ListDomainsRequest
- type ListHealthChecksRequest
- type ListInstancesRequest
- type ListReleasesRequest
- type ListRoutesRequest
- type ListSecretsRequest
- type ListTenantsAPIRequest
- type ProvisionCertRequest
- type QueryAuditLogAPIRequest
- type RemoveDomainRequest
- type RemoveHealthCheckRequest
- type RemoveRouteRequest
- type RollbackRequest
- type RunHealthCheckRequest
- type ScaleInstanceRequest
- type SetQuotaAPIRequest
- type SetSecretAPIRequest
- type SuspendInstanceRequest
- type SuspendTenantAPIRequest
- type TenantPathRequest
- type UpdateInstanceRequest
- type UpdateRouteAPIRequest
- type UpdateTenantAPIRequest
- type VerifyDomainRequest
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type API ¶
type API struct {
// contains filtered or unexported fields
}
API wires all Forge-style HTTP handlers together.
func (*API) AuthForgeMiddleware ¶
func (a *API) AuthForgeMiddleware() forge.Middleware
AuthForgeMiddleware returns a Forge middleware that performs bearer token authentication. Use this when registering routes into an external Forge router (extension mode).
func (*API) Handler ¶
Handler returns the fully assembled http.Handler with all routes. It creates an internal Forge router, registers all routes with OpenAPI metadata, wraps with auth middleware, and returns the result.
func (*API) RegisterRoutes ¶
RegisterRoutes registers all API routes into the given Forge router with full OpenAPI metadata. Use this for Forge extension integration.
type AddDomainAPIRequest ¶
type AddDomainAPIRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
Hostname string `description:"Fully-qualified domain name" json:"hostname"`
TLSEnabled bool `description:"Enable TLS for this domain" json:"tls_enabled"`
}
AddDomainAPIRequest binds path + body for POST /v1/instances/:instanceId/domains. Body fields are replicated because network.AddDomainRequest has a conflicting InstanceID json tag.
type AddRouteAPIRequest ¶
type AddRouteAPIRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
Path string `description:"Route path pattern" json:"path"`
Port int `description:"Target port" json:"port"`
Protocol string `description:"Protocol (http, grpc)" json:"protocol"`
Weight int `description:"Traffic weight (0-100)" json:"weight"`
}
AddRouteAPIRequest binds path + body for POST /v1/instances/:instanceId/routes. Body fields are replicated because network.AddRouteRequest has a conflicting InstanceID json tag.
type CancelDeploymentRequest ¶
type CancelDeploymentRequest struct {
DeploymentID id.ID `description:"Deployment identifier" path:"deploymentId"`
}
CancelDeploymentRequest binds the path for POST /v1/deployments/:deploymentId/cancel.
type ConfigureHealthCheckAPIRequest ¶
type ConfigureHealthCheckAPIRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
Name string `description:"Health check name" json:"name"`
Type string `description:"Check type (http, tcp, grpc, command)" json:"type"`
Target string `description:"Check target (URL, host:port, etc.)" json:"target"`
Interval time.Duration `description:"Check interval" json:"interval"`
Timeout time.Duration `description:"Check timeout" json:"timeout"`
Retries int `description:"Number of retries" json:"retries"`
}
ConfigureHealthCheckAPIRequest binds path + body for POST /v1/instances/:instanceId/health/checks. Body fields are replicated because health.ConfigureRequest has a conflicting InstanceID json tag.
type CreateInstanceRequest ¶
type CreateInstanceRequest struct {
instance.CreateRequest
}
CreateInstanceRequest binds the body for POST /v1/instances.
type CreateTenantAPIRequest ¶
type CreateTenantAPIRequest struct {
admin.CreateTenantRequest
}
CreateTenantAPIRequest binds the body for POST /v1/admin/tenants.
type DeleteInstanceRequest ¶
type DeleteInstanceRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
DeleteInstanceRequest binds the path for DELETE /v1/instances/:instanceId.
type DeleteSecretRequest ¶
type DeleteSecretRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
Key string `description:"Secret key" path:"key"`
}
DeleteSecretRequest binds the path for DELETE /v1/instances/:instanceId/secrets/:key.
type DeployAPIRequest ¶
type DeployAPIRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
Image string `description:"Container image" json:"image"`
Env map[string]string `description:"Environment overrides" json:"env,omitempty"`
Strategy string `description:"Deploy strategy" json:"strategy,omitempty"`
Notes string `description:"Deploy notes" json:"notes,omitempty"`
CommitSHA string `description:"Git commit SHA" json:"commit_sha,omitempty"`
}
DeployAPIRequest binds path + body for POST /v1/instances/:instanceId/deploy. Body fields are replicated because deploy.DeployRequest has a conflicting InstanceID json tag.
type EmptyRequest ¶
type EmptyRequest struct{}
EmptyRequest is used for endpoints with no parameters.
type GetDeploymentRequest ¶
type GetDeploymentRequest struct {
DeploymentID id.ID `description:"Deployment identifier" path:"deploymentId"`
}
GetDeploymentRequest binds the path for GET /v1/deployments/:deploymentId.
type GetInstanceHealthRequest ¶
type GetInstanceHealthRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
GetInstanceHealthRequest binds the path for GET /v1/instances/:instanceId/health.
type GetInstanceRequest ¶
type GetInstanceRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
GetInstanceRequest binds the path for GET /v1/instances/:instanceId.
type GetReleaseRequest ¶
type GetReleaseRequest struct {
ReleaseID id.ID `description:"Release identifier" path:"releaseID"`
}
GetReleaseRequest binds the path for GET /v1/releases/:releaseID.
type InstanceActionRequest ¶
type InstanceActionRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
InstanceActionRequest binds the path for action endpoints (start, stop, restart, unsuspend).
type InstanceTelemetryRequest ¶
type InstanceTelemetryRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
InstanceTelemetryRequest binds the path for GET telemetry endpoints.
type ListDeploymentsRequest ¶
type ListDeploymentsRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
Cursor string `description:"Pagination cursor" query:"cursor"`
Limit int `description:"Page size (default 20)" query:"limit"`
}
ListDeploymentsRequest binds path + query for GET /v1/instances/:instanceId/deployments.
type ListDomainsRequest ¶
type ListDomainsRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
ListDomainsRequest binds the path for GET /v1/instances/:instanceId/domains.
type ListHealthChecksRequest ¶
type ListHealthChecksRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
ListHealthChecksRequest binds the path for GET /v1/instances/:instanceId/health/checks.
type ListInstancesRequest ¶
type ListInstancesRequest struct {
State string `description:"Filter by instance state" query:"state"`
Label string `description:"Filter by label" query:"label"`
Provider string `description:"Filter by provider" query:"provider"`
Cursor string `description:"Pagination cursor" query:"cursor"`
Limit int `description:"Page size (default 20)" query:"limit"`
}
ListInstancesRequest binds query parameters for GET /v1/instances.
type ListReleasesRequest ¶
type ListReleasesRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
Cursor string `description:"Pagination cursor" query:"cursor"`
Limit int `description:"Page size (default 20)" query:"limit"`
}
ListReleasesRequest binds path + query for GET /v1/instances/:instanceId/releases.
type ListRoutesRequest ¶
type ListRoutesRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
ListRoutesRequest binds the path for GET /v1/instances/:instanceId/routes.
type ListSecretsRequest ¶
type ListSecretsRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
ListSecretsRequest binds the path for GET /v1/instances/:instanceId/secrets.
type ListTenantsAPIRequest ¶
type ListTenantsAPIRequest struct {
Status string `description:"Filter by tenant status" query:"status"`
Cursor string `description:"Pagination cursor" query:"cursor"`
Limit int `description:"Page size (default 50)" query:"limit"`
}
ListTenantsAPIRequest binds query parameters for GET /v1/admin/tenants.
type ProvisionCertRequest ¶
type ProvisionCertRequest struct {
DomainID id.ID `description:"Domain identifier" path:"domainId"`
}
ProvisionCertRequest binds the path for POST /v1/domains/:domainId/cert.
type QueryAuditLogAPIRequest ¶
type QueryAuditLogAPIRequest struct {
admin.AuditQuery
}
QueryAuditLogAPIRequest binds the body for POST /v1/admin/audit.
type RemoveDomainRequest ¶
type RemoveDomainRequest struct {
DomainID id.ID `description:"Domain identifier" path:"domainId"`
}
RemoveDomainRequest binds the path for DELETE /v1/domains/:domainId.
type RemoveHealthCheckRequest ¶
type RemoveHealthCheckRequest struct {
CheckID id.ID `description:"Health check identifier" path:"checkId"`
}
RemoveHealthCheckRequest binds the path for DELETE /v1/health/checks/:checkId.
type RemoveRouteRequest ¶
RemoveRouteRequest binds the path for DELETE /v1/routes/:routeId.
type RollbackRequest ¶
type RollbackRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
ReleaseID id.ID `description:"Release to rollback to" json:"release_id"`
}
RollbackRequest binds path + body for POST /v1/instances/:instanceId/rollback.
type RunHealthCheckRequest ¶
type RunHealthCheckRequest struct {
CheckID id.ID `description:"Health check identifier" path:"checkId"`
}
RunHealthCheckRequest binds the path for POST /v1/health/checks/:checkId/run.
type ScaleInstanceRequest ¶
type ScaleInstanceRequest struct {
instance.ScaleRequest
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
ScaleInstanceRequest binds path + body for POST /v1/instances/:instanceId/scale.
type SetQuotaAPIRequest ¶
type SetQuotaAPIRequest struct {
admin.Quota
TenantID string `description:"Tenant identifier" path:"tenantId"`
}
SetQuotaAPIRequest binds path + body for PUT /v1/admin/tenants/:tenantId/quota.
type SetSecretAPIRequest ¶
type SetSecretAPIRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
Key string `description:"Secret key" json:"key"`
Value string `description:"Secret value" json:"value"`
Type string `description:"Secret type (env, file, tls)" json:"type"`
}
SetSecretAPIRequest binds path + body for POST /v1/instances/:instanceId/secrets. Body fields are replicated because secrets.SetRequest has a conflicting InstanceID json tag.
type SuspendInstanceRequest ¶
type SuspendInstanceRequest struct {
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
Reason string `description:"Suspension reason" json:"reason"`
}
SuspendInstanceRequest binds path + body for POST /v1/instances/:instanceId/suspend.
type SuspendTenantAPIRequest ¶
type SuspendTenantAPIRequest struct {
TenantID string `description:"Tenant identifier" path:"tenantId"`
Reason string `description:"Suspension reason" json:"reason"`
}
SuspendTenantAPIRequest binds path + body for POST /v1/admin/tenants/:tenantId/suspend.
type TenantPathRequest ¶
type TenantPathRequest struct {
TenantID string `description:"Tenant identifier" path:"tenantId"`
}
TenantPathRequest binds the path for tenant endpoints.
type UpdateInstanceRequest ¶
type UpdateInstanceRequest struct {
instance.UpdateRequest
InstanceID id.ID `description:"Instance identifier" path:"instanceId"`
}
UpdateInstanceRequest binds path + body for PATCH /v1/instances/:instanceId.
type UpdateRouteAPIRequest ¶
type UpdateRouteAPIRequest struct {
RouteID id.ID `description:"Route identifier" path:"routeId"`
Path *string `description:"Route path pattern" json:"path,omitempty"`
Weight *int `description:"Traffic weight" json:"weight,omitempty"`
StripPrefix *bool `description:"Strip path prefix" json:"strip_prefix,omitempty"`
}
UpdateRouteAPIRequest binds path + body for PATCH /v1/routes/:routeId.
type UpdateTenantAPIRequest ¶
type UpdateTenantAPIRequest struct {
admin.UpdateTenantRequest
TenantID string `description:"Tenant identifier" path:"tenantId"`
}
UpdateTenantAPIRequest binds path + body for PATCH /v1/admin/tenants/:tenantId.
type VerifyDomainRequest ¶
type VerifyDomainRequest struct {
DomainID id.ID `description:"Domain identifier" path:"domainId"`
}
VerifyDomainRequest binds the path for POST /v1/domains/:domainId/verify.
Source Files