flaps

package
v0.9.8 Latest Latest
Warning

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

Go to latest
Published: Aug 25, 2026 License: Apache-2.0 Imports: 26 Imported by: 5

Documentation

Index

Constants

View Source
const (
	ManagedPostgresStatusReady  = "ready"
	ManagedPostgresStatusFailed = "failed"
	ManagedPostgresStatusError  = "error"
)

Statuses a Managed Postgres cluster reports while provisioning. The API documents "failed" as the terminal failure status; "error" is declared too because the service behind it reports that spelling for the same state.

Variables

View Source
var ErrFlapsGone = &FlapsError{ResponseStatusCode: http.StatusGone}

ErrFlapsGone is returned when the API reports a resource as gone (HTTP 410). Managed Postgres returns it for a cluster that has already been deleted.

View Source
var ErrFlapsNotFound = &FlapsError{ResponseStatusCode: http.StatusNotFound}
View Source
var NonceHeader = "fly-machine-lease-nonce"

Functions

func GetErrorRequestID

func GetErrorRequestID(err error) string

func GetErrorTraceID added in v0.1.5

func GetErrorTraceID(err error) string

func IsNameTakenError added in v0.9.5

func IsNameTakenError(err error) bool

IsNameTakenError reports whether err is a rejection of an app name that is already in use.

Prefer this over matching the error's text: it reads the status code the API sets, and falls back to the message only when there is no code at all. The fallback covers two cases and is not vestigial:

  • a client running against a Fly.io API that predates the status code, and
  • app creation that never went through the Machines API at all, such as the extension providers that create their apps over GraphQL, where nothing sets a status code in the first place.

Note what the fallback deliberately does not match: a collision that races past the validation and trips the database constraint instead is reported with a generic message covering every unique constraint the platform has, not just app names. Telling that one apart needs context only the server has, so the API classifies it there and reports it here as the name_taken code.

func Retry added in v0.1.19

func Retry(ctx context.Context, op func() error) error

Retry the given operation with exponential backoff up to 1 minute.

Types

type App added in v0.1.67

type App struct {
	ID                string `json:"id"`
	Name              string `json:"name"`
	InternalNumericID int32  `json:"internal_numeric_id"`
	Network           string `json:"network"`
	Status            string `json:"status"`

	MachineCount int64 `json:"machine_count"`
	VolumeCount  int64 `json:"volume_count"`

	Organization AppOrganizationInfo `json:"organization"`

	// hashid.appname.fly.dev, for ACME HTTP-01 pointing only to v6
	CnameTarget string `json:"cname_target"`
	// a role like "postgres_cluster" or "remote-docker-builder"
	AppRole string `json:"app_role"`
}

func (*App) Deployed added in v0.1.67

func (a *App) Deployed() bool

func (*App) IsPostgresApp added in v0.1.67

func (a *App) IsPostgresApp() bool

type AppOrganizationInfo added in v0.1.67

type AppOrganizationInfo struct {
	Name              string `json:"name"`
	Slug              string `json:"slug"`
	InternalNumericID int32  `json:"internal_numeric_id"`
}

type AssignIPRequest added in v0.1.67

type AssignIPRequest struct {
	Type         string `json:"type"`
	Region       string `json:"region"`
	Organization string `json:"org_slug"`
	Network      string `json:"network"`
	ServiceName  string `json:"service_name"`
}

type Client

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

func NewWithOptions

func NewWithOptions(ctx context.Context, opts NewClientOpts) (*Client, error)

func (*Client) AcquireLease

func (f *Client) AcquireLease(ctx context.Context, appName, machineID string, ttl *int) (*fly.MachineLease, error)

func (*Client) AppNameAvailable added in v0.1.67

func (f *Client) AppNameAvailable(ctx context.Context, name string) (bool, error)

AppNameAvailable reports whether name is free to use for a new app.

App names are a single global namespace, so a name can be taken by an app this client cannot see. The API does not hide that: it looks the name up globally and then refuses the read, so a name held by another organization comes back as a 403 and counts as taken just as much as an app we can read. Only a 404 means the name is free.

Any other failure is returned as-is, alongside a false that means "not available" rather than "taken", because such a failure says nothing either way about the name. That includes a 401, which is what an unauthenticated or unusable token gets: reporting it as "taken" would tell the caller their name is in use when the truth is that nobody asked the question successfully.

func (*Client) AssignIP added in v0.1.67

func (f *Client) AssignIP(ctx context.Context, appName string, req AssignIPRequest) (res *IPAssignment, err error)

func (*Client) CheckCertificate added in v0.3.1

func (f *Client) CheckCertificate(ctx context.Context, appName, hostname string) (*fly.CertificateDetailResponse, error)

Triggers DNS validation + ACME issuance if required.

func (*Client) Cordon

func (f *Client) Cordon(ctx context.Context, appName, machineID string, nonce string) (err error)

func (*Client) CreateACMECertificate added in v0.3.1

func (f *Client) CreateACMECertificate(ctx context.Context, appName string, req fly.CreateCertificateRequest) (*fly.CertificateDetailResponse, error)

Add a hostname and start ACME issuance.

func (*Client) CreateApp

func (f *Client) CreateApp(ctx context.Context, in CreateAppRequest) (app *App, err error)

func (*Client) CreateCustomCertificate added in v0.3.1

func (f *Client) CreateCustomCertificate(ctx context.Context, appName string, req fly.ImportCertificateRequest) (*fly.CertificateDetailResponse, error)

Add a custom certificate. Will not start ACME issuance if not already present.

func (*Client) CreateManagedPostgresCluster added in v0.9.4

func (f *Client) CreateManagedPostgresCluster(ctx context.Context, req CreateManagedPostgresClusterRequest) (ManagedPostgresCluster, error)

func (*Client) CreateVolume

func (f *Client) CreateVolume(ctx context.Context, appName string, req fly.CreateVolumeRequest) (*fly.Volume, error)

func (*Client) CreateVolumeSnapshot

func (f *Client) CreateVolumeSnapshot(ctx context.Context, appName, volumeId string) error

func (*Client) DecryptSecretKey added in v0.1.46

func (f *Client) DecryptSecretKey(ctx context.Context, appName, name string, ciphertext, assoc []byte, version *uint64) (*fly.DecryptSecretKeyResp, error)

func (*Client) DeleteACMECertificate added in v0.3.1

func (f *Client) DeleteACMECertificate(ctx context.Context, appName, hostname string) error

Removes ACME certificates and stops renewals, leaving a custom certificate in place.

func (*Client) DeleteApp added in v0.1.67

func (f *Client) DeleteApp(ctx context.Context, name string) error

func (*Client) DeleteAppSecret added in v0.1.46

func (f *Client) DeleteAppSecret(ctx context.Context, appName, name string) (*fly.DeleteAppSecretResp, error)

func (*Client) DeleteCertificate added in v0.3.1

func (f *Client) DeleteCertificate(ctx context.Context, appName, hostname string) error

Removes hostname and all certificates.

func (*Client) DeleteCustomCertificate added in v0.3.1

func (f *Client) DeleteCustomCertificate(ctx context.Context, appName, hostname string) error

Removes a custom certificate, leaving the ACME certificates in place.

func (*Client) DeleteIPAssignment added in v0.1.67

func (f *Client) DeleteIPAssignment(ctx context.Context, appName, ip string) (err error)

func (*Client) DeleteManagedPostgresCluster added in v0.9.8

func (f *Client) DeleteManagedPostgresCluster(ctx context.Context, id string) error

func (*Client) DeleteMetadata

func (f *Client) DeleteMetadata(ctx context.Context, appName, machineID, key string) error

func (*Client) DeleteSecretKey added in v0.1.46

func (f *Client) DeleteSecretKey(ctx context.Context, appName, name string) error

func (*Client) DeleteVolume

func (f *Client) DeleteVolume(ctx context.Context, appName, volumeId string) (*fly.Volume, error)

func (*Client) Destroy

func (f *Client) Destroy(ctx context.Context, appName string, input fly.RemoveMachineInput, nonce string) (err error)

func (*Client) EncryptSecretKey added in v0.1.46

func (f *Client) EncryptSecretKey(ctx context.Context, appName, name string, plaintext, assoc []byte, version *uint64) (*fly.EncryptSecretKeyResp, error)

func (*Client) Exec

func (f *Client) Exec(ctx context.Context, appName, machineID string, in *fly.MachineExecRequest) (*fly.MachineExecResponse, error)

func (*Client) ExtendVolume

func (f *Client) ExtendVolume(ctx context.Context, appName, volumeId string, size_gb int) (*fly.Volume, bool, error)

func (*Client) FindLease

func (f *Client) FindLease(ctx context.Context, appName, machineID string) (*fly.MachineLease, error)

func (*Client) GenerateSecretKey added in v0.1.46

func (f *Client) GenerateSecretKey(ctx context.Context, appName, name string, typ string) (*fly.SetSecretKeyResp, error)

func (*Client) Get

func (f *Client) Get(ctx context.Context, appName, machineID string) (*fly.Machine, error)

func (*Client) GetAllVolumes

func (f *Client) GetAllVolumes(ctx context.Context, appName string) ([]fly.Volume, error)

func (*Client) GetApp added in v0.1.67

func (f *Client) GetApp(ctx context.Context, name string) (app *App, err error)

func (*Client) GetAppSecrets added in v0.1.46

func (f *Client) GetAppSecrets(ctx context.Context, appName, name string, version *uint64, showSecrets bool) (*fly.AppSecret, error)

func (*Client) GetCertificate added in v0.3.1

func (f *Client) GetCertificate(ctx context.Context, appName, hostname string) (*fly.CertificateDetailResponse, error)

func (*Client) GetIPAssignments added in v0.1.67

func (f *Client) GetIPAssignments(ctx context.Context, appName string) (res *ListIPAssignmentsResponse, err error)

func (*Client) GetManagedPostgresCluster added in v0.9.4

func (f *Client) GetManagedPostgresCluster(ctx context.Context, id string) (ManagedPostgresCluster, error)

func (*Client) GetManagedPostgresUserCredentials added in v0.9.4

func (f *Client) GetManagedPostgresUserCredentials(ctx context.Context, id, username string) (ManagedPostgresUserCredentials, error)

func (*Client) GetMany

func (f *Client) GetMany(ctx context.Context, appName string, machineIDs []string) ([]*fly.Machine, error)

func (*Client) GetMetadata

func (f *Client) GetMetadata(ctx context.Context, appName, machineID string) (map[string]string, error)

func (*Client) GetPlacements added in v0.1.47

func (f *Client) GetPlacements(ctx context.Context, request *GetPlacementsRequest) ([]RegionPlacement, error)

func (*Client) GetProcesses

func (f *Client) GetProcesses(ctx context.Context, appName, machineID string) (fly.MachinePsResponse, error)

func (*Client) GetRegions added in v0.1.45

func (f *Client) GetRegions(ctx context.Context) (*RegionData, error)

func (*Client) GetSecretKey added in v0.1.46

func (f *Client) GetSecretKey(ctx context.Context, appName, name string, version *uint64) (*fly.SecretKey, error)

func (*Client) GetVolume

func (f *Client) GetVolume(ctx context.Context, appName, volumeId string) (*fly.Volume, error)

func (*Client) GetVolumeSnapshots

func (f *Client) GetVolumeSnapshots(ctx context.Context, appName, volumeId string) ([]fly.VolumeSnapshot, error)

func (*Client) GetVolumes

func (f *Client) GetVolumes(ctx context.Context, appName string) ([]fly.Volume, error)

func (*Client) Kill

func (f *Client) Kill(ctx context.Context, appName, machineID string) (err error)

func (*Client) Launch

func (f *Client) Launch(ctx context.Context, appName string, builder fly.LaunchMachineInput) (out *fly.Machine, err error)

func (*Client) List

func (f *Client) List(ctx context.Context, appName, state string) ([]*fly.Machine, error)

func (*Client) ListActive

func (f *Client) ListActive(ctx context.Context, appName string) ([]*fly.Machine, error)

ListActive returns only non-destroyed that aren't in a reserved process group.

func (*Client) ListAppSecrets added in v0.1.46

func (f *Client) ListAppSecrets(ctx context.Context, appName string, version *uint64, showSecrets bool) ([]fly.AppSecret, error)

func (*Client) ListApps added in v0.1.67

func (f *Client) ListApps(ctx context.Context, req ListAppsRequest) (apps []App, err error)

func (*Client) ListCertificates added in v0.3.1

func (f *Client) ListCertificates(ctx context.Context, appName string, opts *ListCertificatesOpts) (*fly.ListCertificatesResponse, error)

func (*Client) ListFlyAppsMachines

func (f *Client) ListFlyAppsMachines(ctx context.Context, appName string) ([]*fly.Machine, *fly.Machine, error)

ListFlyAppsMachines returns apps that are part of Fly Launch. Destroyed machines and console machines are excluded. Unlike other List functions, this function retries multiple times.

func (*Client) ListManagedPostgresClusters added in v0.9.8

func (f *Client) ListManagedPostgresClusters(ctx context.Context, req ListManagedPostgresClustersRequest) ([]ManagedPostgresClusterSummary, error)

func (*Client) ListSecretKeys added in v0.1.46

func (f *Client) ListSecretKeys(ctx context.Context, appName string, version *uint64) ([]fly.SecretKey, error)

func (*Client) NewRequest

func (f *Client) NewRequest(ctx context.Context, method, path string, in interface{}, headers map[string][]string) (*http.Request, error)

func (*Client) RefreshLease

func (f *Client) RefreshLease(ctx context.Context, appName, machineID string, ttl *int, nonce string) (*fly.MachineLease, error)

func (*Client) ReleaseLease

func (f *Client) ReleaseLease(ctx context.Context, appName, machineID, nonce string) error

func (*Client) Restart

func (f *Client) Restart(ctx context.Context, appName string, in fly.RestartMachineInput, nonce string) (err error)

func (*Client) SetAppSecret added in v0.1.46

func (f *Client) SetAppSecret(ctx context.Context, appName, name string, value string) (*fly.SetAppSecretResp, error)

func (*Client) SetMetadata

func (f *Client) SetMetadata(ctx context.Context, appName, machineID, key, value string) error

func (*Client) SetSecretKey added in v0.1.46

func (f *Client) SetSecretKey(ctx context.Context, appName, name string, typ string, value []byte) (*fly.SetSecretKeyResp, error)

func (*Client) SignSecretKey added in v0.1.46

func (f *Client) SignSecretKey(ctx context.Context, appName, name string, plaintext []byte, version *uint64) (*fly.SignSecretKeyResp, error)

func (*Client) Start

func (f *Client) Start(ctx context.Context, appName, machineID string, nonce string) (out *fly.MachineStartResponse, err error)

func (*Client) Stop

func (f *Client) Stop(ctx context.Context, appName string, in fly.StopMachineInput, nonce string) (err error)

func (*Client) Suspend added in v0.1.17

func (f *Client) Suspend(ctx context.Context, appName, machineID, nonce string) error

func (*Client) Uncordon

func (f *Client) Uncordon(ctx context.Context, appName, machineID string, nonce string) (err error)

func (*Client) Update

func (f *Client) Update(ctx context.Context, appName string, builder fly.LaunchMachineInput, nonce string) (out *fly.Machine, err error)

func (*Client) UpdateAppSecrets added in v0.1.51

func (f *Client) UpdateAppSecrets(ctx context.Context, appName string, values map[string]*string) (*fly.UpdateAppSecretsResp, error)

UpdateAppSecrets can set and delete secrets. Nil secret values are deleted, while others are set.

func (*Client) UpdateVolume

func (f *Client) UpdateVolume(ctx context.Context, appName, volumeId string, req fly.UpdateVolumeRequest) (*fly.Volume, error)

func (*Client) VerifySecretKey added in v0.1.46

func (f *Client) VerifySecretKey(ctx context.Context, appName, name string, plaintext, sig []byte, version *uint64) error

func (*Client) Wait

func (f *Client) Wait(ctx context.Context, appName string, machineID string, waitOpts ...WaitOption) (err error)

func (*Client) WaitForApp

func (f *Client) WaitForApp(ctx context.Context, name string) error

type CreateAppRequest added in v0.1.67

type CreateAppRequest struct {
	Name      string `json:"name"`
	Org       string `json:"org_slug"`
	Network   string `json:"network"`
	AppRoleID string `json:"app_role_id"`
}

type CreateManagedPostgresClusterRequest added in v0.9.4

type CreateManagedPostgresClusterRequest struct {
	OrgSlug        string `json:"org_slug"`
	Name           string `json:"name,omitempty"`
	Region         string `json:"region"`
	Plan           string `json:"plan"`
	DiskSizeGB     int    `json:"disk_size_gb,omitempty"`
	PGMajorVersion string `json:"pg_major_version,omitempty"`
	PostGISEnabled bool   `json:"postgis_enabled"`
}

CreateManagedPostgresClusterRequest is the body for POST /v1/postgres.

type ErrorRequestID

type ErrorRequestID interface {
	ErrRequestID() string
}

TODO: we might not actually need an interface type here

type ErrorStatusCode

type ErrorStatusCode interface {
	error
	StatusCode() *StatusCode
}

type ErrorTraceID added in v0.1.5

type ErrorTraceID interface {
	ErrTraceID() string
}

type ExtendVolumeRequest

type ExtendVolumeRequest struct {
	SizeGB int `json:"size_gb"`
}

type ExtendVolumeResponse

type ExtendVolumeResponse struct {
	Volume       *fly.Volume `json:"volume"`
	NeedsRestart bool        `json:"needs_restart"`
}

type FlapsError

type FlapsError struct {
	OriginalError      error
	ResponseStatusCode int
	ResponseBody       []byte
	FlyRequestId       string
	TraceID            string
}

func (*FlapsError) ErrRequestID

func (fe *FlapsError) ErrRequestID() string

func (*FlapsError) ErrTraceID added in v0.1.5

func (fe *FlapsError) ErrTraceID() string

func (*FlapsError) Error

func (fe *FlapsError) Error() string

func (*FlapsError) Is

func (fe *FlapsError) Is(target error) bool

func (*FlapsError) ResponseBodyString

func (fe *FlapsError) ResponseBodyString() string

func (*FlapsError) StatusCode

func (fe *FlapsError) StatusCode() *StatusCode

func (*FlapsError) Suggestion

func (fe *FlapsError) Suggestion() string

func (*FlapsError) Unwrap

func (fe *FlapsError) Unwrap() error

type GetPlacementsRequest added in v0.1.47

type GetPlacementsRequest struct {
	// Resource requirements for the Machine to simulate. Defaults to a performance-1x machine
	ComputeRequirements *fly.MachineGuest `json:"compute"`

	// Region expression for placement as a comma-delimited set of regions or aliases.
	// Defaults to "[region],any", to prefer the API endpoint's local region with any other region as fallback.
	Region string `json:"region"`

	// Number of machines to simulate placement.
	// Defaults to 0, which returns the org-specific limit for each region.
	Count uint64 `json:"count"`

	VolumeName      string `json:"volume_name"`
	VolumeSizeBytes uint64 `json:"volume_size_bytes"`

	// Optional weights to override default placement preferences.
	Weights *Weights `json:"weights"`

	Org string `json:"org_slug"`
}

type GetPlacementsResponse added in v0.1.47

type GetPlacementsResponse struct {
	Regions []RegionPlacement
}

type IPAssignment added in v0.1.67

type IPAssignment struct {
	IP          string    `json:"ip"`
	Region      string    `json:"region"`
	ServiceName string    `json:"service_name"`
	Shared      bool      `json:"shared"`
	CreatedAt   time.Time `json:"created_at"`
}

func (IPAssignment) IsFlycast added in v0.1.67

func (ip IPAssignment) IsFlycast() bool

type ListAppsRequest added in v0.1.69

type ListAppsRequest struct {
	OrgSlug string
	// AppRole is optional
	AppRole string
}

type ListCertificatesOpts added in v0.3.1

type ListCertificatesOpts struct {
	Limit  int
	Cursor string
	Filter string
}

type ListIPAssignmentsResponse added in v0.1.67

type ListIPAssignmentsResponse struct {
	IPs []IPAssignment `json:"ips"`
}

type ListManagedPostgresClustersRequest added in v0.9.8

type ListManagedPostgresClustersRequest struct {
	OrgSlug        string
	IncludeDeleted bool
}

ListManagedPostgresClustersRequest contains the query parameters for GET /v1/postgres.

type ManagedPostgresAttachedApp added in v0.9.4

type ManagedPostgresAttachedApp struct {
	Name string `json:"name"`
}

type ManagedPostgresCluster added in v0.9.4

type ManagedPostgresCluster struct {
	ID             string                       `json:"id"`
	Name           string                       `json:"name"`
	Status         string                       `json:"status"`
	Region         string                       `json:"region"`
	Plan           string                       `json:"plan"`
	DiskSizeGB     int                          `json:"disk_size_gb"`
	CPUs           int                          `json:"cpus"`
	CPUKind        string                       `json:"cpu_kind"`
	MemoryMB       int                          `json:"memory_mb"`
	Replicas       int                          `json:"replicas"`
	PGMajorVersion string                       `json:"pg_major_version"`
	PostGISEnabled bool                         `json:"postgis_enabled"`
	Endpoints      ManagedPostgresEndpoints     `json:"endpoints"`
	Organization   ManagedPostgresOrganization  `json:"organization"`
	CreatedAt      string                       `json:"created_at"`
	AttachedApps   []ManagedPostgresAttachedApp `json:"attached_apps"`
}

ManagedPostgresCluster is the public projection of a Managed Postgres cluster returned by create/show.

type ManagedPostgresClusterSummary added in v0.9.8

type ManagedPostgresClusterSummary struct {
	ID           string                       `json:"id"`
	Name         string                       `json:"name"`
	Status       string                       `json:"status"`
	Region       string                       `json:"region"`
	Plan         string                       `json:"plan"`
	CreatedAt    string                       `json:"created_at"`
	DeletedAt    string                       `json:"deleted_at"`
	AttachedApps []ManagedPostgresAttachedApp `json:"attached_apps"`
}

ManagedPostgresClusterSummary is the public projection returned by GET /v1/postgres.

type ManagedPostgresEndpoint added in v0.9.4

type ManagedPostgresEndpoint struct {
	Host string `json:"host"`
	Port int    `json:"port"`
}

type ManagedPostgresEndpoints added in v0.9.4

type ManagedPostgresEndpoints struct {
	Primary struct {
		Direct ManagedPostgresEndpoint `json:"direct"`
		Pooler ManagedPostgresEndpoint `json:"pooler"`
	} `json:"primary"`
}

type ManagedPostgresOrganization added in v0.9.4

type ManagedPostgresOrganization struct {
	Name string `json:"name"`
	Slug string `json:"slug"`
}

type ManagedPostgresUserCredentials added in v0.9.4

type ManagedPostgresUserCredentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

ManagedPostgresUserCredentials is the response from GET /v1/postgres/:id/users/:username/credentials.

type NewClientOpts

type NewClientOpts struct {
	// optional, sent with requests
	UserAgent string

	Tokens *tokens.Tokens

	// optional:
	Logger fly.Logger

	FlyForceInstanceID string

	// optional, used to construct the underlying HTTP client
	Transport http.RoundTripper

	// optional; if non-nil, attaches the Fly-Client-* headers/UA suffix
	// derived from these signals
	ClientSignals *clientsignals.Signals
}

type RegionData added in v0.1.67

type RegionData struct {
	Regions []fly.Region `json:"Regions"`
	Nearest string       `json:"Nearest"`
}

type RegionPlacement added in v0.1.47

type RegionPlacement struct {
	Region      string
	Count       int
	Concurrency int
}

type StatusCode

type StatusCode string

func GetErrorStatusCode

func GetErrorStatusCode(err error) *StatusCode

type WaitOption added in v0.4.0

type WaitOption func(*waitOptions)

func WithWaitFromEventID added in v0.4.0

func WithWaitFromEventID(fromEventID string) WaitOption

func WithWaitStates added in v0.4.0

func WithWaitStates(states ...string) WaitOption

func WithWaitTimeout added in v0.4.0

func WithWaitTimeout(timeout time.Duration) WaitOption

func WithWaitVersion added in v0.4.0

func WithWaitVersion(version string) WaitOption

type Weights added in v0.1.47

type Weights map[string]int64

Weights override default placement preferences. `region` (default 50) prefers regions closer to the target region. `spread` (default 1) prefers spreading placements across different hosts instead of packed on the same host.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL