deployengine

package module
v0.0.0-...-4f221f3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 22, 2025 License: Apache-2.0 Imports: 20 Imported by: 0

README

deploy engine client library

Coverage Security Rating Maintainability Rating

The deploy engine client library for Go that provides a client for the deploy engine API.

Installation

go get github.com/newstack-cloud/celerity/libs/deploy-engine-client

Usage

HTTP request
package main

import (
    "github.com/newstack-cloud/celerity/libs/deploy-engine-client"
)

func main() {
    // Create a new client
    client := deployengine.NewClient(
        // Configure the client with a custom endpoint and credentials.
        deployengine.WithClientEndpoint("https://deploy.my-service.io"),
        deployengine.WithClientCeleritySigv1KeyPair(
            &deployengine.CeleritySignatureKeyPair{
                KeyID: os.Getenv("DEPLOY_ENGINE_KEY_ID"),
                SecretKey: os.Getenv("DEPLOY_ENGINE_SECRET_KEY"),
            },
        ),
    )

    bpValidation, err := client.GetBlueprintValidation(
        context.Background(),
        "c6f69b85-a6e8-4374-8c6f-8b4539d1142b",
    )
    // handle error and use the retrieved blueprint validation ...
}
Stream events
package main

import (
    "github.com/newstack-cloud/celerity/libs/deploy-engine-client"
)

func main() {
    // Set up client ...
    streamTo := make(chan types.BlueprintValidationEvent)
    errChan := make(chan error)
    err := client.StreamBlueprintValidationEvents(
        context.Background(),
        "c6f69b85-a6e8-4374-8c6f-8b4539d1142b",
        streamTo,
        errChan,
    )
    if err != nil {
        // handle error
    }

    // You'll most likely want to spawn a goroutine
    // to collect and handle events from the stream.
    for {
        select {
        case event, ok := <-streamTo:
            if !ok {
                // channel closed
                return
            }
            // handle event
        case err := <-errChan:
            // handle error
            return
        }
    }
}

Additional documentation

Documentation

Index

Constants

View Source 
const (
	// CelerityAPIKeyHeaderName is the name of the header
	// used to pass the API key for authentication.
	CelerityAPIKeyHeaderName = "Celerity-Api-Key"
	// AuthorisationHeaderName is the name of the header
	// used to send a bearer token issued by an OAuth2 or OIDC provider.
	AuthorisationHeaderName = "Authorization"
	// ChannelTypeValidation is the channel type identifier
	// for validation events.
	ChannelTypeValidation = "validation"
	// ChannelTypeChangeset is the channel type identifier
	// for change staging (change set) events.
	ChannelTypeChangeset = "changeset"
	// ChannelTypeDeployment is the channel type identifier
	// for deployment events.
	ChannelTypeDeployment = "deployment"
)
View Source 
const (
	// DefaultEndpoint specifies the default endpoint to use to connect
	// to the Celerity Deploy Engine when no endpoint is specified for
	// the client.
	// There is no default production endpoint for the Deploy Engine
	// so it makes more sense for the end user to default to a version
	// of the Deploy Engine that is running locally as a part of a standard
	// Celerity installation or otherwise.
	DefaultEndpoint = "http://localhost:8325"
	// DefaultProtocol specifies the default connection protocol to use
	// to connect to the Celerity Deploy Engine when no protocol is specified
	// for the client.
	DefaultProtocol = ConnectProtocolTCP
	// DefaultUnixDomainSocket specifies the default Unix domain socket
	// file to use to connect to the Celerity Deploy Engine when
	// the protocol is set to `ConnectProtocolUnixDomainSocket`.
	DefaultUnixDomainSocket = "/tmp/celerity.sock"
	// DefaultAuthMethod specifies the default authentication method to use
	// to connect to the Celerity Deploy Engine when no authentication method
	// is specified for the client.
	// This defaults to the Celerity Signature v1 method which is the more secure
	// of the simpler authentication methods.
	DefaultAuthMethod = AuthMethodCeleritySignatureV1
	// DefaultRequestTimeout specifies the default timeout to use for HTTP requests
	// to the Celerity Deploy Engine when no timeout is specified for the client.
	// This only applies to standard HTTP requests and not streaming requests.
	DefaultRequestTimeout = 60 * time.Second
	// DefaultStreamTimeout specifies the default timeout to use for streaming
	// requests to the Celerity Deploy Engine when no timeout is specified for
	// the client.
	// This default is high to allow for long-running processes like deployments
	// of infrastructure that can take a long time to complete.
	DefaultStreamTimeout = 3 * time.Hour
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AuthConfig 

type AuthConfig struct {
	// Method specifies the authentication method to use for requests
	// to the Celerity Deploy Engine.
	Method AuthMethod
	// APIKey is the API key to use to authenticate requests
	// when Method is `AuthMethodAPIKey`.
	APIKey string
	// OAuth2Config is the OAuth configuration to use to authenticate
	// requests when Method is `AuthMethodOAuth2`.
	OAuth2Config *OAuth2Config
	// CeleritySignatureKeyPair is the Celerity Signature v1 key pair
	// to use to authenticate requests when Method is `AuthMethodCeleritySignatureV1`.
	CeleritySignatureKeyPair *sigv1.KeyPair
	// CeleritySignatureCustomHeaders is a list of custom headers
	// to include in the signed message for the Celerity Signature v1
	// authentication method.
	CeleritySignatureCustomHeaders []string
}

type AuthMethod 

type AuthMethod int32

AuthMethod represents the method of authentication that should be used to connect to an instance of the Celerity Deploy Engine. 

const (
	// AuthMethodAPIKey indicates that the client should
	// authenticate using an API key.
	AuthMethodAPIKey AuthMethod = iota
	// AuthMethodOAuth2 indicates that the client should
	// authenticate using OAuth where a token is obtained
	// from a third-party identity provider through the
	// client credentials grant type.
	// This version of the Deploy Engine supports OAuth2/OIDC
	// providers that produce JWTs for access tokens that are compatible
	// with the auth method documentation that can be found here:
	// https://www.celerityframework.io/docs/auth/jwts
	AuthMethodOAuth2
	// AuthMethodCeleritySignatureV1 indicates that the client should
	// authenticate using the Celerity Signature v1 method.
	// See: https://www.celerityframework.io/docs/auth/signature-v1
	AuthMethodCeleritySignatureV1
)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides a client implementation of the Celerity Deploy Engine API. This supports v1 of the API including the v1 streaming interface.

func NewClient 

func NewClient(
	opts ...ClientOption,
) (*Client, error)

NewClient creates a client for an instance of the Celerity Deploy Engine v1 API. If an OAuth2/OIDC provider is configured, the client will fetch the discovery document from the provider if a token endpoint is not provided during client creation.

func (*Client) CleanupBlueprintValidations 

func (c *Client) CleanupBlueprintValidations(
	ctx context.Context,
) error

CleanupBlueprintValidations cleans up blueprint validation that are older than the retention period configured for the Deploy Engine instance. This is the `POST {baseURL}/v1/validations/cleanup` API endpoint.

func (*Client) CleanupChangesets 

func (c *Client) CleanupChangesets(
	ctx context.Context,
) error

CleanupChangesets cleans up change sets that are older than the retention period configured for the Deploy Engine instance. This is the `POST {baseURL}/v1/deployments/changes/cleanup` API endpoint.

func (*Client) CleanupEvents 

func (c *Client) CleanupEvents(
	ctx context.Context,
) error

CleanupEvents cleans up events that are older than the retention period configured for the Deploy Engine instance.

This will clean up events for all processes including blueprint validations, change staging and deployments. This will not clean up the resources themselves, only the events that are associated with them. You can clean up change sets and blueprint validations using the dedicated methods. This is the `POST {baseURL}/v1/events/cleanup` API endpoint.

func (*Client) CreateBlueprintInstance 

func (c *Client) CreateBlueprintInstance(
	ctx context.Context,
	payload *types.BlueprintInstancePayload,
) (*state.InstanceState, error)

CreateBlueprintInstance (Deploy New) creates a new blueprint deployment instance. This will start the deployment process for the provided blueprint document and change set. It will return a blueprint instance resource containing an ID that can be used to stream deployment events as they occur. This is the `POST {baseURL}/v1/deployments/instances` API endpoint.

func (*Client) CreateBlueprintValidation 

func (c *Client) CreateBlueprintValidation(
	ctx context.Context,
	payload *types.CreateBlueprintValidationPayload,
	query *types.CreateBlueprintValidationQuery,
) (*manage.BlueprintValidation, error)

CreateBlueprintValidation creates a new blueprint validation for the provided blueprint document and starts the validation process. This will return an ID that can be used to stream the validation events as they occur. This is the `POST {baseURL}/v1/validations` API endpoint.

func (*Client) CreateChangeset 

func (c *Client) CreateChangeset(
	ctx context.Context,
	payload *types.CreateChangesetPayload,
) (*manage.Changeset, error)

CreateChangeset creates a change set for a blueprint deployment. This will start a change staging process for the provided blueprint document and return an ID that can be used to retrieve the change set or stream change staging events.

If a valid instance ID or name is provided, a change set will be created by comparing the provided blueprint document with the current state of the existing blueprint instance.

Creating a change set should be carried out in preparation for deploying new blueprint instances or updating existing blueprint instances.

This is the `POST {baseURL}/v1/deployments/changes` API endpoint.

func (*Client) DestroyBlueprintInstance 

func (c *Client) DestroyBlueprintInstance(
	ctx context.Context,
	instanceID string,
	payload *types.DestroyBlueprintInstancePayload,
) (*state.InstanceState, error)

DestroyBlueprintInstance destroys a blueprint deployment instance. This will start the destroy process for the provided change set. It will return the current state of the blueprint instance, the same ID provided should be used to stream destroy events as they occur. This is the `POST {baseURL}/v1/deployments/instances/{id}/destroy` API endpoint.

func (*Client) GetBlueprintInstance 

func (c *Client) GetBlueprintInstance(
	ctx context.Context,
	instanceID string,
) (*state.InstanceState, error)

GetBlueprintInstance retrieves a blueprint deployment instance. This will return the current status of the deployment along with the current state of the blueprint intance. This is the `GET {baseURL}/v1/deployments/instances/{id}` API endpoint.

func (*Client) GetBlueprintInstanceExports 

func (c *Client) GetBlueprintInstanceExports(
	ctx context.Context,
	instanceID string,
) (map[string]*state.ExportState, error)

GetBlueprintInstanceExports retrieves the exports from a blueprint deployment instance. This will return the exported fields from the blueprint instance. This is the `GET {baseURL}/v1/deployments/instances/{id}/exports` API endpoint.

func (*Client) GetBlueprintValidation 

func (c *Client) GetBlueprintValidation(
	ctx context.Context,
	validationID string,
) (*manage.BlueprintValidation, error)

GetBlueprintValidation retrieves metadata and status information about a blueprint validation. To get validation events (diagnostics), use the `StreamBlueprintValidationEvents` method. This is the `GET {baseURL}/v1/validations/{id}` API endpoint.

func (*Client) GetChangeset 

func (c *Client) GetChangeset(
	ctx context.Context,
	changesetID string,
) (*manage.Changeset, error)

GetChangeset retrieves a change set for a blueprint deployment. This will return the current status of the change staging process. If complete, the response will include a full set of changes that will be applied when deploying the change set. This is the `GET {baseURL}/v1/deployments/changes/{id}` API endpoint.

func (*Client) StreamBlueprintInstanceEvents 

func (c *Client) StreamBlueprintInstanceEvents(
	ctx context.Context,
	instanceID string,
	streamTo chan<- types.BlueprintInstanceEvent,
	errChan chan<- error,
) error

StreamBlueprintInstanceEvents streams events from the current deployment process for the given blueprint instance ID.

This will stream events for new deployments, updates and for destroying a blueprint instance.

This will produce a stream of events as they occur or that have recently occurred.

For a blueprint instance that has been destroyed, this stream will no longer be available to new connections once the destroy process has been successfully completed.

Any HTTP errors that occur when estabilishing a connection or unexpected failures in the deployment process will be sent to the provided error channel.

This comes with built-in re-connect logic that makes use of the the `Last-Event-ID` header to resume the stream from the last event received.

This is the `GET {baseURL}/v1/deployments/instances/{id}/stream` API SSE stream endpoint.

func (*Client) StreamBlueprintValidationEvents 

func (c *Client) StreamBlueprintValidationEvents(
	ctx context.Context,
	validationID string,
	streamTo chan<- types.BlueprintValidationEvent,
	errChan chan<- error,
) error

StreamBlueprintValidationEvents streams events from a blueprint validation process. This will produce a stream of events as they occur or that have recently occurred. Any HTTP errors that occur when estabilishing a connection will be sent to the provided error channel. This comes with built-in re-connect logic that makes use of the the `Last-Event-ID` header to resume the stream from the last event received. This is the `GET {baseURL}/v1/validations/{id}/stream` API SSE stream endpoint.

func (*Client) StreamChangeStagingEvents 

func (c *Client) StreamChangeStagingEvents(
	ctx context.Context,
	changesetID string,
	streamTo chan<- types.ChangeStagingEvent,
	errChan chan<- error,
) error

StreamChangeStagingEvents streams events from the change staging process for the given change set ID. This will produce a stream of events as they occur or that have recently occurred. Any HTTP errors that occur when estabilishing a connection will be sent to the provided error channel. This comes with built-in re-connect logic that makes use of the the `Last-Event-ID` header to resume the stream from the last event received. This is the `GET {baseURL}/v1/deployments/changes/{id}/stream` API SSE stream endpoint.

func (*Client) UpdateBlueprintInstance 

func (c *Client) UpdateBlueprintInstance(
	ctx context.Context,
	instanceID string,
	payload *types.BlueprintInstancePayload,
) (*state.InstanceState, error)

UpdateBlueprintInstance (Deploy Existing) updates an existing blueprint deployment instance. This will start the deployment process for the provided blueprint document and change set. It will return the current state of the blueprint instance, the same ID provided should be used to stream deployment events as they occur. This is the `PATCH {baseURL}/v1/deployments/instances/{id}` API endpoint.

type ClientOption 

type ClientOption func(*Client)

ClientOption is a function that configures the client.

func WithClientAPIKey 

func WithClientAPIKey(apiKey string) ClientOption

WithClientAPIKey configures the API key to use to authenticate to the Celerity Deploy Engine. This is only used when the authentication method is set to `AuthMethodAPIKey`. When an API key is not provided, the client will not be able to authenticate to the Celerity Deploy Engine.

func WithClientAuthMethod 

func WithClientAuthMethod(method AuthMethod) ClientOption

WithClientAuthMethod configures the authentication method to use to connect to the Celerity Deploy Engine. This can be either `AuthMethodAPIKey`, `AuthMethodOAuth2` or `AuthMethodCeleritySignatureV1`. When an authentication method is not provided, the client will default to `AuthMethodCeleritySignatureV1`.

func WithClientCeleritySigv1CustomHeaders 

func WithClientCeleritySigv1CustomHeaders(headers []string) ClientOption

WithClientCeleritySigv1CustomHeaders configures the custom headers to use to authenticate to the Celerity Deploy Engine using the Celerity Signature v1 method. This is only used when the authentication method is set to `AuthMethodCeleritySignatureV1`. Celerity Signature v1 configuration must be provided when the authentication method is set to `AuthMethodCeleritySignatureV1`. This is a list of headers that will be included in the signed message when creating the signature header.

func WithClientCeleritySigv1KeyPair 

func WithClientCeleritySigv1KeyPair(keyPair *sigv1.KeyPair) ClientOption

WithClientCeleritySigv1KeyPair configures the Celerity Signature v1 configuration to use to authenticate to the Celerity Deploy Engine. This is only used when the authentication method is set to `AuthMethodCeleritySignatureV1`. Celerity Signature v1 configuration must be provided when the authentication method is set to `AuthMethodCeleritySignatureV1`.

func WithClientClock 

func WithClientClock(clock core.Clock) ClientOption

WithClientClock configures the clock to use to get the current time and measure elapsed time. When a clock is not provided, the client will default to the current system clock.

func WithClientConnectProtocol 

func WithClientConnectProtocol(protocol ConnectProtocol) ClientOption

WithClientConnectProtocol configures the protocol to use to connect to the Celerity Deploy Engine. This can be either `ConnectProtocolTCP` or `ConnectProtocolUnixDomainSocket`. When a protocol is not provided, the client will default to `ConnectProtocolTCP`.

func WithClientEndpoint 

func WithClientEndpoint(endpoint string) ClientOption

WithClientEndpoint configures the endpoint to use to connect to the Celerity Deploy Engine. When an endpoint is not provided, the client will use `http://localhost:8325`. When the protocol is set to `ConnectProtocolUnixDomainSocket`, the endpoint will be ignored and the client will use a placeholder endpoint of "http://unix" to make sure the underlying HTTP client does not try to resolve the endpoint via DNS.

func WithClientHTTPRoundTripper 

func WithClientHTTPRoundTripper(
	createRoundTripper func(transport *http.Transport) http.RoundTripper,
) ClientOption

WithClientHTTPRoundTripper configures the HTTP round tripper to use to connect to the Celerity Deploy Engine. This is used to configure the HTTP client with a custom transport that supports retries and other features. This is a function that takes a transport and returns a round tripper as there is core configuration that needs to be applied to the underlying transport (e.g. Unix domain socket support) in all cases. This round tripper will only be used for standard HTTP requests and not streaming requests. When a round tripper is not provided, the client will default to a transport that supports retries with exponential backoff and jitter configured with reasonable defaults.

func WithClientLogger 

func WithClientLogger(logger core.Logger) ClientOption

WithClientLogger configures the logger to use to log messages from the Celerity Deploy Engine client. When a logger is not provided, the client will default to a no-op logger that does not log any messages.

func WithClientOAuth2Config 

func WithClientOAuth2Config(config *OAuth2Config) ClientOption

WithClientOAuth2Config configures the OAuth2 configuration to use to authenticate to the Celerity Deploy Engine. This is only used when the authentication method is set to `AuthMethodOAuth2`. OAuth2 configuration must be provided when the authentication method is set to `AuthMethodOAuth2`.

func WithClientRequestTimeout 

func WithClientRequestTimeout(timeout time.Duration) ClientOption

WithClientRequestTimeout configures the request timeout to use to connect to the Celerity Deploy Engine. This is used to configure the HTTP client with a custom timeout for requests. When a timeout is not provided, the client will default to 60 seconds. This only applies to standard HTTP requests and not streaming requests.

func WithClientStreamTimeout 

func WithClientStreamTimeout(timeout time.Duration) ClientOption

WithClientStreamTimeout configures the stream timeout to use to connect to the Celerity Deploy Engine. This is used to configure the HTTP client with a custom timeout for streaming requests. When a timeout is not provided, the client will default to 3 hours.

func WithClientUnixDomainSocket 

func WithClientUnixDomainSocket(socket string) ClientOption

WithClientUnixDomainSocket configures the Unix domain socket to use to connect to the Celerity Deploy Engine. This is only used when the protocol is set to `ConnectProtocolUnixDomainSocket`. When a Unix domain socket is not provided, the client will default to `/tmp/celerity.sock`.

type ConnectProtocol 

type ConnectProtocol int32

ConnectProtocol represents the protocol used to connect to an instance of the Celerity Deploy Engine. 

const (
	// ConnectProtocolTCP indicates that the client should connect
	// to the Celerity Deploy Engine using HTTP over TCP.
	ConnectProtocolTCP ConnectProtocol = iota
	// ConnectProtocolUnixDomainSocket indicates that the client should connect
	// to the Celerity Deploy Engine using a Unix domain socket.
	ConnectProtocolUnixDomainSocket
)

type OAuth2Config 

type OAuth2Config struct {
	// ProviderBaseURL is the base URL of the OAuth2 or OIDC provider.
	// This is the URL from which the client will use to obtain
	// the discovery document for the provider at either `/.well-known/openid-configuration`
	// or `/.well-known/oauth-authorization-server`.
	// When TokenEndpoint is set, this value is ignored.
	ProviderBaseURL string
	// TokenEndpoint is the fully qualified URL of the token endpoint to use to obtain
	// an access token from the OAuth2 or OIDC provider.
	// When this value is left empty, the client will attempt to obtain the discovery document
	// from the ProviderBaseURL and use the token endpoint from that document.
	TokenEndpoint string
	// ClientID is used as a part of the client credentials grant type
	// to obtain an access token from the OAuth2 or OIDC provider.
	ClientID string
	// ClientSecret is used as a part of the client credentials grant type
	// to obtain an access token from the OAuth2 or OIDC provider.
	ClientSecret string
}

OAuth2Config contains the configuration for gaining access to the Deploy Engine using an OAuth2 or OIDC provider.

Source Files

View all Source files

Directories

Path Synopsis
internal
httputils
oauth2
sseconfig
The github.com/r3labs/sse/v2 package provides an interface for creating clients that takes options but doesn't implement any of the options.
 The github.com/r3labs/sse/v2 package provides an interface for creating clients that takes options but doesn't implement any of the options.
testutils
Provides a stub implementation of a Deploy Engine server.
 Provides a stub implementation of a Deploy Engine server.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.