lib

Documentation

Index

• Constants
• func IsDeploy() bool
• func ListenPort() string
• func ListenPortOffset(offset uint16) string
• func Port() int
• func PortOffset(offset uint16) int
• func PrivateHost() string
• func StorageDir(source ...string) (out string)
• func StorageFile(source ...string) (out string)
• func StoragePath(source string) (out string)
• func VirtualLatency(from, to string) time.Duration
• type ControlInfo
  • func Discover(ctx context.Context) (*ControlInfo, error)
  • func (ci *ControlInfo) ByAddr(addr net.Addr) *InstanceInfo
  • func (ci *ControlInfo) ByAddrPort(ap netip.AddrPort) *InstanceInfo
  • func (ci *ControlInfo) PeerAddrOffset(offset uint16) map[string]netip.AddrPort
• type FlyReplayHeader
  • func (fr *FlyReplayHeader) ForResponseHeader() string
  • func (fr *FlyReplayHeader) SetResponse(h http.Header) bool
• type InstanceInfo
  • func Self() InstanceInfo
  • func (i *InstanceInfo) Addr() netip.AddrPort
  • func (i *InstanceInfo) AddrOffset(offset uint16) netip.AddrPort
  • func (i *InstanceInfo) AsUint() (out uint64, ok bool)
  • func (i *InstanceInfo) IsSelf() bool

Constants

const (
	// PortRange is used in dev mode: each instance is given a port range on localhost.
	// Requests for ports via the helpers outside this range will panic.
	PortRange = 128
)

Functions

func IsDeploy

func IsDeploy() bool

IsDeploy returns whether this is deployed to Fly.

func ListenPort

func ListenPort() string

ListenPort returns a string for a HTTP server to listen on.

func ListenPortOffset

func ListenPortOffset(offset uint16) string

ListenPortOffset returns a string for a HTTP server to listen on.

func Port

func Port() int

Port returns the primary port of this service. In production this is probably 8080.

func PortOffset

func PortOffset(offset uint16) int

PortOffset returns this port plus an offset.

func PrivateHost

func PrivateHost() string

PrivateHost returns the internal private host that should be listened on for non-public ports. This is probably optional, because likely only PORT is exposed to the real world.

func StorageDir

func StorageDir(source ...string) (out string)

StorageDir creates and returns the given directory in prod/dev. Protects against escape from this path. But probably not against untrusted user input. This must be within a registered mount on the prod machine. In a local environment, places this in `$HOME/.fly/hangar/<machine>/mount/<path>`.

func StorageFile

func StorageFile(source ...string) (out string)

StorageFile creates and returns the given directory in prod/dev, stripping the last component (ignoring it). Protects against escape from this path. But probably not against untrusted user input. This must be within a registered mount on the prod machine. In a local environment, places this in `$HOME/.fly/hangar/<machine>/mount/<path>`.

func StoragePath

func StoragePath(source string) (out string)

StorageDir creates and returns the given directory in prod/dev. Protects against escape from this path. But probably not against untrusted user input. This must be within a registered mount on the prod machine. In a local environment, places this in `$HOME/.fly/hangar/<machine>/mount/<path>`.

func VirtualLatency

func VirtualLatency(from, to string) time.Duration

VirtualLatency calculates a fake, consistent latency between two named regions. It's the same in either direction. This always returns zero in deploy contexts.

Types

type ControlInfo

type ControlInfo struct {
	Now       int64          `json:"now"`
	Instances []InstanceInfo `json:"instances"`
	Unknown   bool           `json:"unknown,omitempty"` // whether there was a (hopefully) transient error in fetching
}

func Discover

func Discover(ctx context.Context) (*ControlInfo, error)

Discover finds mesh instances for this process. This excludes ourselves. This takes ~1ms in deploy (DNS lookup) relying on Fly's replication magic.

func (*ControlInfo) ByAddr

func (ci *ControlInfo) ByAddr(addr net.Addr) *InstanceInfo

ByAddr returns the InstanaceInfo by the given address (tcp or udp).

func (*ControlInfo) ByAddrPort

func (ci *ControlInfo) ByAddrPort(ap netip.AddrPort) *InstanceInfo

ByAddrPort returns the InstanceInfo by the given address and port.

func (*ControlInfo) PeerAddrOffset

func (ci *ControlInfo) PeerAddrOffset(offset uint16) map[string]netip.AddrPort

Peers returns the map of peer address/port combos.

type FlyReplayHeader

type FlyReplayHeader struct {
	Region    string `json:"region,omitempty"`
	Instance  string `json:"instance,omitempty"`
	App       string `json:"app,omitempty"`
	State     string `json:"state,omitempty"`
	Elsewhere bool   `json:"elsewhere,omitempty"`
	Now       int64  `json:"t,omitempty"`
}

FlyReplayHeader can be used to construct a reply that asks another instance to handle a request, rather than handling it directly.

func (*FlyReplayHeader) ForResponseHeader

func (fr *FlyReplayHeader) ForResponseHeader() string

ForResponseHeader writes this FlyReplayHeader to attach to a header output.

func (*FlyReplayHeader) SetResponse

func (fr *FlyReplayHeader) SetResponse(h http.Header) bool

SetResponse applies this FlyReplayHeader to a response for your userspace code.

type InstanceInfo

type InstanceInfo struct {
	Machine string `json:"machine"` // the machine ID reported by Fly
	Region  string `json:"region"`  // the 3-character region code
	Address string `json:"address"` // the private IPv6 of this instance
	Port    uint16 `json:"port"`    // the default port of this instance
	// contains filtered or unexported fields
}

func Self

func Self() InstanceInfo

Self immediately returns information about ourself as a mesh instance.

func (*InstanceInfo) Addr

func (i *InstanceInfo) Addr() netip.AddrPort

Addr returns the netip.AddrPort for the target instance using its default public port.

func (*InstanceInfo) AddrOffset

func (i *InstanceInfo) AddrOffset(offset uint16) netip.AddrPort

AddrOffset returns the netip.AddrPort reflecting the target machine plus a port offset.

func (*InstanceInfo) AsUint

func (i *InstanceInfo) AsUint() (out uint64, ok bool)

AsUint attempts to coerce the hex-encoded machine ID into a uint64. It's possible that Fly changes the way machines are represented, but as of 2023-11, they are 14-character hex codes (56 bits).

func (*InstanceInfo) IsSelf

func (i *InstanceInfo) IsSelf() bool

IsSelf returns whether this InstanceInfo represents the currently running machine.