base-layer/releasekit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Document neutral forge delivery and preflight

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-01 18:38:03 +00:00
parent c3f6eeb6df
commit cbdba90014
12 changed files with 370 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
delivery.go
View File

@@ -29,7 +29,8 @@ const (
DeliveryUnknown DeliveryState = "unknown"
)
// Forge selects the hosted delivery backend.
// Forge selects the hosted delivery backend. A delivery request must select a
// supported value explicitly; the destination URL does not select a backend.
type Forge string
const (
@@ -39,6 +40,7 @@ const (
// DeliveryDestination supplies an explicitly selected hosted destination.
type DeliveryDestination struct {
// Forge selects the adapter that interprets the destination fields.
Forge Forge
BaseURL string
Owner string
@@ -51,11 +53,16 @@ type DeliveryDestination struct {
type DeliveryPreflightFailureKind string
const (
DeliveryPreflightMissingCredential DeliveryPreflightFailureKind = "missing_credential"
DeliveryPreflightInvalidCredential DeliveryPreflightFailureKind = "invalid_credential"
// DeliveryPreflightMissingCredential means no nonblank credential was supplied.
DeliveryPreflightMissingCredential DeliveryPreflightFailureKind = "missing_credential"
// DeliveryPreflightInvalidCredential means the selected service rejected the credential.
DeliveryPreflightInvalidCredential DeliveryPreflightFailureKind = "invalid_credential"
// DeliveryPreflightInsufficientPermissions means a required delivery permission is known to be absent.
DeliveryPreflightInsufficientPermissions DeliveryPreflightFailureKind = "insufficient_permissions"
// DeliveryPreflightInaccessibleDestination means the credential cannot access the selected repository.
DeliveryPreflightInaccessibleDestination DeliveryPreflightFailureKind = "inaccessible_destination"
DeliveryPreflightUnavailable DeliveryPreflightFailureKind = "unavailable"
// DeliveryPreflightUnavailable means the service response could not verify access.
DeliveryPreflightUnavailable DeliveryPreflightFailureKind = "unavailable"
)
// DeliveryPreflightError reports a classified failure to verify a destination.
@@ -128,14 +135,17 @@ type DeliveryResult struct {
Uncertain []DeliveryAsset
}
// Deliver verifies the selected local tag and hosted source, then creates or
// finds its release page and adds any missing declared build assets. Build
// requests are compiled into temporary storage that Deliver removes on return.
// Prebuilt artifacts remain caller-owned and are not removed. Both paths
// validate source identity and artifact contents before hosted writes.
// Deliver requires an explicit supported destination forge. It checks the local
// request and source, then performs read-only credential preflight before a
// managed build or full artifact verification. It verifies the selected local
// tag and hosted source, then creates or finds its release page and adds any
// missing declared build assets. Prebuilt artifacts remain caller-owned. Local
// artifact contents are verified after preflight and before hosted writes.
// Module selection and declaration links resolve from the captured commit.
// Page-only delivery can use a sparse checkout with available committed objects;
// managed builds require their selected source files in the working tree.
// Preflight failures return a [DeliveryPreflightError] and leave State at
// [DeliveryNotAttempted].
func Deliver(ctx context.Context, request DeliveryRequest) (DeliveryResult, error) {
result := DeliveryResult{Version: request.Version, State: DeliveryNotAttempted}
backend, err := deliveryBackend(request.Destination)
@@ -174,6 +184,10 @@ func Deliver(ctx context.Context, request DeliveryRequest) (DeliveryResult, erro
// PreflightDelivery checks destination credentials and repository access using
// read-only backend operations. It does not require a checkout or published tag.
// The result verifies only the access and permission evidence exposed by the
// selected backend; it does not guarantee that a later write will succeed.
// Failures are returned as [DeliveryPreflightError] values when classified by
// the backend, and retain their underlying cause for errors.Is and errors.As.
func PreflightDelivery(ctx context.Context, destination DeliveryDestination) error {
backend, err := deliveryBackend(destination)
if err != nil {