README
¶
pkg/server/handler
Purpose
This package is the API application layer for compute.
At the top level it is intentionally thinner than the equivalent handler layer
in region. Most of the interesting behaviour lives in the resource-specific
clients beneath it:
regionread-side capability exposure for regions, flavors, and imagesinstancecreate/read/update/delete plus operational verbs over the hidden backing serverversionrelease metadata for the deployed compute API binary
So this package is best understood as the transport and request-shaping layer that ties those two pieces together under one HTTP API.
Invariants And Guard Rails
v2Instanceis the main intended API surface for compute lifecycle.- The older
v1-shaped endpoints here are read-side capability discovery over region resources, not compute-owned server lifecycle. GET /api/versionis an authenticated service metadata endpoint. It returns the build name and version from the running binary, setsCache-Control: no-cache, and does not expose or mutate compute resources.- Top-level handlers do final request parsing, response writing, and HTTP error normalization, then delegate actual policy and mutation logic downward.
- Read-side region/flavor/image endpoints impersonate the caller into region so region remains the authority on visibility.
- Flavor discovery excludes region flavors marked
pinnedOnly, because compute instances do not exposeinfrastructureRefhost pinning and those flavors would be rejected by region during backing server creation. - The
.well-known/openid-protected-resourceendpoint is cacheable and is part of the service trust contract, not just a convenience route.
Architectural Split
This package makes compute's split surface visible:
GetApiV1Organizations...Regions/Flavors/Imagesis effectively curated catalog access into regionGet /api/versionis authenticated deployment metadata for clients and CI gates that need to identify the exact compute server buildGet/Post/Put/Delete /api/v2/instances...is compute's own higher-level abstraction over hidden server lifecycle
That split is one of the real differences from region, where server lifecycle
itself is directly exposed as a first-class root.
Caveats
- The interesting invariants are mostly not in the top-level handler methods. They live in ./instance and in the controller layer.
- The package still carries mixed API eras:
v1compatibility-shaped read endpoints alongsidev2instance lifecycle. - Error and path handling are deliberately centralized here, so small mistakes in transport wiring can affect every route.
TODO
- Document whether the remaining
v1read-side catalog routes should remain as long-term service surface or be replaced by a flatterv2capability model. - Revisit whether the top-level split between curated region read APIs and compute-owned instance lifecycle needs to be made clearer in the public API documentation itself.
Cross-Package Context
- ./instance contains the actual instance behaviour and most of the service-specific policy
- ../README.md documents how this handler layer is composed into the live HTTP server and trust pipeline
Documentation
¶
Index ¶
- func HandleError(w http.ResponseWriter, r *http.Request, err error)
- func MethodNotAllowed(w http.ResponseWriter, r *http.Request)
- func NotFound(w http.ResponseWriter, r *http.Request)
- type Handler
- func (h *Handler) DeleteApiV2InstancesInstanceID(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
- func (h *Handler) GetApiV1OrganizationsOrganizationIDRegions(w http.ResponseWriter, r *http.Request, ...)
- func (h *Handler) GetApiV1OrganizationsOrganizationIDRegionsRegionIDFlavors(w http.ResponseWriter, r *http.Request, ...)
- func (h *Handler) GetApiV1OrganizationsOrganizationIDRegionsRegionIDImages(w http.ResponseWriter, r *http.Request, ...)
- func (h *Handler) GetApiV2Instances(w http.ResponseWriter, r *http.Request, params openapi.GetApiV2InstancesParams)
- func (h *Handler) GetApiV2InstancesInstanceID(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
- func (h *Handler) GetApiV2InstancesInstanceIDConsoleoutput(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter, ...)
- func (h *Handler) GetApiV2InstancesInstanceIDConsolesession(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
- func (h *Handler) GetApiV2InstancesInstanceIDSshkey(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
- func (h *Handler) GetApiVersion(w http.ResponseWriter, r *http.Request)
- func (h *Handler) GetWellKnownOpenidProtectedResource(w http.ResponseWriter, r *http.Request)
- func (h *Handler) PostApiV2Instances(w http.ResponseWriter, r *http.Request)
- func (h *Handler) PostApiV2InstancesInstanceIDReboot(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter, ...)
- func (h *Handler) PostApiV2InstancesInstanceIDSnapshot(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
- func (h *Handler) PostApiV2InstancesInstanceIDStart(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
- func (h *Handler) PostApiV2InstancesInstanceIDStop(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
- func (h *Handler) PutApiV2InstancesInstanceID(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HandleError ¶
func HandleError(w http.ResponseWriter, r *http.Request, err error)
HandleError is called when the router has trouble parsong paths.
func MethodNotAllowed ¶
func MethodNotAllowed(w http.ResponseWriter, r *http.Request)
MethodNotAllowed is called from the router when a method is not found for a path.
Types ¶
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
func New ¶
func New(client client.Client, namespace string, options *Options, identity identityapi.ClientWithResponsesInterface, region regionapi.ClientWithResponsesInterface) (*Handler, error)
func (*Handler) DeleteApiV2InstancesInstanceID ¶ added in v1.11.0
func (h *Handler) DeleteApiV2InstancesInstanceID(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
func (*Handler) GetApiV1OrganizationsOrganizationIDRegions ¶ added in v0.1.6
func (h *Handler) GetApiV1OrganizationsOrganizationIDRegions(w http.ResponseWriter, r *http.Request, organizationID openapi.OrganizationIDParameter)
func (*Handler) GetApiV1OrganizationsOrganizationIDRegionsRegionIDFlavors ¶
func (h *Handler) GetApiV1OrganizationsOrganizationIDRegionsRegionIDFlavors(w http.ResponseWriter, r *http.Request, organizationID openapi.OrganizationIDParameter, regionID openapi.RegionIDParameter)
func (*Handler) GetApiV1OrganizationsOrganizationIDRegionsRegionIDImages ¶
func (h *Handler) GetApiV1OrganizationsOrganizationIDRegionsRegionIDImages(w http.ResponseWriter, r *http.Request, organizationID openapi.OrganizationIDParameter, regionID openapi.RegionIDParameter)
func (*Handler) GetApiV2Instances ¶ added in v1.11.0
func (h *Handler) GetApiV2Instances(w http.ResponseWriter, r *http.Request, params openapi.GetApiV2InstancesParams)
func (*Handler) GetApiV2InstancesInstanceID ¶ added in v1.11.0
func (h *Handler) GetApiV2InstancesInstanceID(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
func (*Handler) GetApiV2InstancesInstanceIDConsoleoutput ¶ added in v1.11.0
func (h *Handler) GetApiV2InstancesInstanceIDConsoleoutput(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter, params openapi.GetApiV2InstancesInstanceIDConsoleoutputParams)
func (*Handler) GetApiV2InstancesInstanceIDConsolesession ¶ added in v1.11.0
func (h *Handler) GetApiV2InstancesInstanceIDConsolesession(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
func (*Handler) GetApiV2InstancesInstanceIDSshkey ¶ added in v1.11.0
func (h *Handler) GetApiV2InstancesInstanceIDSshkey(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
func (*Handler) GetApiVersion ¶ added in v1.16.6
func (h *Handler) GetApiVersion(w http.ResponseWriter, r *http.Request)
func (*Handler) GetWellKnownOpenidProtectedResource ¶ added in v1.14.0
func (h *Handler) GetWellKnownOpenidProtectedResource(w http.ResponseWriter, r *http.Request)
GetWellKnownOpenidProtectedResource implements RFC 9728.
func (*Handler) PostApiV2Instances ¶ added in v1.11.0
func (h *Handler) PostApiV2Instances(w http.ResponseWriter, r *http.Request)
func (*Handler) PostApiV2InstancesInstanceIDReboot ¶ added in v1.11.0
func (h *Handler) PostApiV2InstancesInstanceIDReboot(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter, params openapi.PostApiV2InstancesInstanceIDRebootParams)
func (*Handler) PostApiV2InstancesInstanceIDSnapshot ¶ added in v1.13.0
func (h *Handler) PostApiV2InstancesInstanceIDSnapshot(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
func (*Handler) PostApiV2InstancesInstanceIDStart ¶ added in v1.11.0
func (h *Handler) PostApiV2InstancesInstanceIDStart(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
func (*Handler) PostApiV2InstancesInstanceIDStop ¶ added in v1.11.0
func (h *Handler) PostApiV2InstancesInstanceIDStop(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
func (*Handler) PutApiV2InstancesInstanceID ¶ added in v1.11.0
func (h *Handler) PutApiV2InstancesInstanceID(w http.ResponseWriter, r *http.Request, instanceID openapi.InstanceIDParameter)
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.