machinesapi

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Mar 19, 2025 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ExternalURL is reachable from the public internet.
	ExternalURL, _ = url.Parse("https://api.machines.dev")

	// InternalURL is only reachable from machines running on Fly.io.
	InternalURL, _ = url.Parse("http://_api.internal:4280")

	DefaultClient = &Client{}
)

Functions

This section is empty.

Types

type Access

type Access struct {

	// OrgSlug is the slug of the organization being accessed.
	OrgSlug *string `json:"org_slug,omitempty"`

	// AppName is the name of the app being accessed.
	AppName *string `json:"app_name,omitempty"`

	// VolumeID is the encoded ID of the volume being accessed (e.g.
	// vol_r1p6pln1k9m9j7zr).
	VolumeID *string `json:"volume_id,omitempty"`

	// MachineID is the ID of the machine being accessed (e.g. 7811701f564258).
	MachineID *string `json:"machine_id,omitempty"`

	// Action is the action being taken on the specified resource. This is the
	// combination of individual action characters (e.g "rw")
	//   - r: read
	//   - w: write
	//   - c: create
	//   - d: delete
	//   - C: control
	Action resset.Action `json:"action,omitempty"`

	// OrgFeature is a named set of functionality associated with the
	// organization. If this is specified, the OrgSlug field must be set.
	//   - wg: WireGuard peers
	//   - builder: remote builders
	//   - addon: addons
	//   - membership: organization membership
	//   - billing: billing
	//   - litefs-cloud: LiteFS Cloud
	//   - authentication: authentication settings
	OrgFeature *string `json:"org_feature,omitempty"`

	// AppFeature is a named set of functionality associated with the app. If
	// this is specified, the AppName field must be set.
	//   - images: images in the fly.io registry
	AppFeature *string `json:"app_feature,omitempty"`

	// MachineFeature is a named set of functionality associated with the
	// machine. If this is specified, the Machine field must be set.
	//   - metadata: machine metadata service
	//   - oidc: OIDC tokens
	MachineFeature *string `json:"machine_feature,omitempty"`

	// Mutation is the GraphQL mutation being performed.
	Mutation *string `json:"mutation,omitempty"`

	// SourceMachine is the machine ID of the actor attempting access.
	SourceMachine *string `json:"source_machine,omitempty"`

	// Command is the command being executed on a machine. If this is specified,
	// the Machine must be set.
	Command []string `json:"command,omitempty"`

	// StorageObject is the storage object being accessed. If this is specified,
	// the OrgSlug must be set.
	StorageObject *resset.Prefix `json:"storage_object,omitempty"`
}

The Machines API takes a different Access than is used in the flyio package. Most macaroon consumers don't know about numeric IDs or what apps belong to which orgs, etc, without making a bunch of extra API calls. The Machines API does this work for us.

Access describes an attempt to access a resource. Resources are hierarchical it is necessary to specify parents of the resource being accessed. For example, if you specify a machine feature, you must also specify the machine that the feature belongs to. This is not necessary for the Org->App, App->Volume, or App->Machine relationships because the Machines API can figure those out itself. Multiple resources at the same level of hierarchy cannot be specified (e.g. can't specify Machine and Volume). The hierarchy is as follows:

-> Organization
  -> OrgFeature
  -> StorageObject
  -> App
    -> AppFeature
    -> Volume
    -> Machine
      -> MachineFeature
      -> Command

Other fields on this struct are contextual, falling outside of this hierarchy. For example, the SourceMachine field specifies which fly.io machine is attempting the access, allowing caveats to restrict access to individual machines.

type Client

type Client struct {
	HTTP    http.RoundTripper
	BaseURL *url.URL
	// contains filtered or unexported fields
}

Client is a client for the Machines API tokens API. It implements bundle.Verifier for token verification. It also allows for authorization checking by external clients.

func (*Client) Authorize

func (c *Client) Authorize(ctx context.Context, header string, access *Access) (*flyio.Access, error)

Authorize checks if the tokens in the provided header are authorized for the provided access. It returns the flyio.Access object that was authorized.

func (*Client) AuthorizeBundle

func (c *Client) AuthorizeBundle(ctx context.Context, bun *bundle.Bundle, access *Access) (*flyio.Access, error)

AuthorizeBundle is the same as Authorize, but works on an already parsed Bundle of tokens.

func (*Client) Verify

Verify implements bundle.Verifier using the Fly.io Machines API.

type ServerError

type ServerError struct {
	Err        string `json:"error"`
	StatusCode int    `json:"-"`
}

ServerError is an error returned by the Machines API server.

func (*ServerError) Error

func (e *ServerError) Error() string

Jump to

Keyboard shortcuts

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