ReqFly.Machines (req_fly v1.0.0)

Functions for interacting with Fly.io Machines API.

The Machines API provides comprehensive operations for managing Fly.io machines including lifecycle management (create, start, stop, restart), configuration updates, and state monitoring.

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")

# List machines in an app
{:ok, machines} = ReqFly.Machines.list(req, app_name: "my-app")

# Get machine details
{:ok, machine} = ReqFly.Machines.get(req, app_name: "my-app", machine_id: "148ed123456789")

# Create a new machine
config = %{
  image: "flyio/hellofly:latest",
  guest: %{cpus: 1, memory_mb: 256}
}
{:ok, machine} = ReqFly.Machines.create(req, app_name: "my-app", config: config)

# Start a machine
{:ok, _} = ReqFly.Machines.start(req, app_name: "my-app", machine_id: "148ed123456789")

# Stop a machine
{:ok, _} = ReqFly.Machines.stop(req, app_name: "my-app", machine_id: "148ed123456789")

Summary

Functions

create(req, opts)

Creates a new machine in an app.

destroy(req, opts)

Destroys (deletes) a machine.

get(req, opts)

Gets details for a specific machine.

list(req, opts)

Lists all machines in an app.

restart(req, opts)

Restarts a machine.

signal(req, opts)

Sends a signal to a machine.

start(req, opts)

Starts a stopped machine.

stop(req, opts)

Stops a running machine.

update(req, opts)

Updates a machine's configuration.

wait(req, opts)

Waits for a machine to reach a specific state.

Functions

create(req, opts)

@spec create(
  Req.Request.t(),
  keyword()
) :: {:ok, map()} | {:error, ReqFly.Error.t()}

Creates a new machine in an app.

Parameters

req - A Req.Request with ReqFly attached
opts - Options keyword list
- :app_name - Name of the app (required)
- :config - Machine configuration map (required)
- :region - Region to create the machine in (optional)

Returns

{:ok, machine} - Created machine details
{:error, %ReqFly.Error{}} - Error details

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")

config = %{
  image: "flyio/hellofly:latest",
  guest: %{cpus: 1, memory_mb: 256}
}

{:ok, machine} = ReqFly.Machines.create(req,
  app_name: "my-app",
  config: config
)

# With specific region
{:ok, machine} = ReqFly.Machines.create(req,
  app_name: "my-app",
  config: config,
  region: "sjc"
)

destroy(req, opts)

@spec destroy(
  Req.Request.t(),
  keyword()
) :: {:ok, term()} | {:error, ReqFly.Error.t()}

Destroys (deletes) a machine.

Parameters

req - A Req.Request with ReqFly attached
opts - Options keyword list
- :app_name - Name of the app (required)
- :machine_id - ID of the machine (required)

Returns

{:ok, response} - Deletion confirmation
{:error, %ReqFly.Error{}} - Error details

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")
{:ok, _} = ReqFly.Machines.destroy(req,
  app_name: "my-app",
  machine_id: "148ed123456789"
)

get(req, opts)

@spec get(
  Req.Request.t(),
  keyword()
) :: {:ok, map()} | {:error, ReqFly.Error.t()}

Gets details for a specific machine.

Parameters

req - A Req.Request with ReqFly attached
opts - Options keyword list
- :app_name - Name of the app (required)
- :machine_id - ID of the machine (required)

Returns

{:ok, machine} - Machine details
{:error, %ReqFly.Error{}} - Error details

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")
{:ok, machine} = ReqFly.Machines.get(req,
  app_name: "my-app",
  machine_id: "148ed123456789"
)

list(req, opts)

@spec list(
  Req.Request.t(),
  keyword()
) :: {:ok, [map()]} | {:error, ReqFly.Error.t()}

Lists all machines in an app.

Parameters

req - A Req.Request with ReqFly attached
opts - Options keyword list
- :app_name - Name of the app (required)

Returns

{:ok, machines} - List of machine maps
{:error, %ReqFly.Error{}} - Error details

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")
{:ok, machines} = ReqFly.Machines.list(req, app_name: "my-app")

restart(req, opts)

@spec restart(
  Req.Request.t(),
  keyword()
) :: {:ok, term()} | {:error, ReqFly.Error.t()}

Restarts a machine.

Parameters

req - A Req.Request with ReqFly attached
opts - Options keyword list
- :app_name - Name of the app (required)
- :machine_id - ID of the machine (required)

Returns

{:ok, response} - Restart confirmation
{:error, %ReqFly.Error{}} - Error details

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")
{:ok, _} = ReqFly.Machines.restart(req,
  app_name: "my-app",
  machine_id: "148ed123456789"
)

signal(req, opts)

@spec signal(
  Req.Request.t(),
  keyword()
) :: {:ok, term()} | {:error, ReqFly.Error.t()}

Sends a signal to a machine.

Parameters

req - A Req.Request with ReqFly attached
opts - Options keyword list
- :app_name - Name of the app (required)
- :machine_id - ID of the machine (required)
- :signal - Signal to send (e.g., "SIGTERM", "SIGKILL") (required)

Returns

{:ok, response} - Signal confirmation
{:error, %ReqFly.Error{}} - Error details

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")
{:ok, _} = ReqFly.Machines.signal(req,
  app_name: "my-app",
  machine_id: "148ed123456789",
  signal: "SIGTERM"
)

start(req, opts)

@spec start(
  Req.Request.t(),
  keyword()
) :: {:ok, term()} | {:error, ReqFly.Error.t()}

Starts a stopped machine.

Parameters

req - A Req.Request with ReqFly attached
opts - Options keyword list
- :app_name - Name of the app (required)
- :machine_id - ID of the machine (required)

Returns

{:ok, response} - Start confirmation
{:error, %ReqFly.Error{}} - Error details

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")
{:ok, _} = ReqFly.Machines.start(req,
  app_name: "my-app",
  machine_id: "148ed123456789"
)

stop(req, opts)

@spec stop(
  Req.Request.t(),
  keyword()
) :: {:ok, term()} | {:error, ReqFly.Error.t()}

Stops a running machine.

Parameters

req - A Req.Request with ReqFly attached
opts - Options keyword list
- :app_name - Name of the app (required)
- :machine_id - ID of the machine (required)

Returns

{:ok, response} - Stop confirmation
{:error, %ReqFly.Error{}} - Error details

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")
{:ok, _} = ReqFly.Machines.stop(req,
  app_name: "my-app",
  machine_id: "148ed123456789"
)

update(req, opts)

@spec update(
  Req.Request.t(),
  keyword()
) :: {:ok, map()} | {:error, ReqFly.Error.t()}

Updates a machine's configuration.

Parameters

req - A Req.Request with ReqFly attached
opts - Options keyword list
- :app_name - Name of the app (required)
- :machine_id - ID of the machine (required)
- :config - Updated machine configuration map (required)

Returns

{:ok, machine} - Updated machine details
{:error, %ReqFly.Error{}} - Error details

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")

config = %{
  image: "flyio/hellofly:latest",
  guest: %{cpus: 2, memory_mb: 512}
}

{:ok, machine} = ReqFly.Machines.update(req,
  app_name: "my-app",
  machine_id: "148ed123456789",
  config: config
)

wait(req, opts)

@spec wait(
  Req.Request.t(),
  keyword()
) :: {:ok, term()} | {:error, ReqFly.Error.t()}

Waits for a machine to reach a specific state.

Parameters

req - A Req.Request with ReqFly attached
opts - Options keyword list
- :app_name - Name of the app (required)
- :machine_id - ID of the machine (required)
- :instance_id - Instance ID to wait for (optional)
- :state - State to wait for (e.g., "started", "stopped") (optional)
- :timeout - Timeout in seconds (optional)

Returns

{:ok, response} - State confirmation
{:error, %ReqFly.Error{}} - Error details

Examples

req = Req.new() |> ReqFly.attach(token: "fly_token")

{:ok, _} = ReqFly.Machines.wait(req,
  app_name: "my-app",
  machine_id: "148ed123456789",
  state: "started",
  timeout: 60
)

{:ok, _} = ReqFly.Machines.wait(req,
  app_name: "my-app",
  machine_id: "148ed123456789",
  instance_id: "01H3JK...",
  state: "stopped"
)