class Ptero::Application

Overview

A class for interacting with the application API.

Defined in:

application.cr

Constant Summary

DEFAULT_HEADERS = {"User-Agent" => "Ptero.cr Application v#{VERSION}", "Content-Type" => "application/json", "Accept" => "application/json"}

Constructors

Instance Method Summary

Constructor Detail

def self.new(url : String | URI, key : String, rest : Crest::Resource | Nil = nil) #

[View source]

Instance Method Detail

def create_node(*, name : String, description : String | Nil = nil, location_id : Int32, public : Bool, fqdn : String, scheme : String, behind_proxy : Bool, memory : Int32, memory_overallocate : Int32, disk : Int32, disk_overallocate : Int32, daemon_base : String, daemon_sftp : Int32, daemon_listen : Int32, maintenance_mode : Bool, upload_size : Int32) : Models::Node #

Creates a node on the panel with the given fields.

Fields

  • name: the name of the node
  • description (optional): the description of the node
  • location_id: the ID of the location to create the node under
  • public: whether the node should be publicly accessible
  • fqdn: the Fully Qualified Domain Name (FQDN) for the node
  • scheme: the HTTP scheme for the node to use
  • behind_proxy: whether the node is (or should be) behind a proxy
  • memory: the memory limit for the node
  • memory_overallocate: the amount of memory the node can overallocate
  • disK: the disk limit for the node
  • disk_overallocate: the amount of disk the node can overallocate
  • daemon_base: the daemon base for the node
  • daemon_sftp: the SFTP port for the node
  • daemon_listen: the listen port for the node
  • maintenance_mode: whether the node should be set to maintenance mode on creation
  • upload_size: the upload size limit for the node

[View source]
def create_server(*, name : String, description : String | Nil = nil, external_id : String | Nil = nil, user : Int32, egg : Int32, docker_image : String, startup : String, environment : Hash(String, String | Int32 | Bool | Nil), skip_scripts : Bool, oom_disabled : Bool, limits : Models::Limits, feature_limits : Models::FeatureLimits, allocation : Models::AllocationData, start_on_completion : Bool) : Models::AppServer #

Creates a server on the panel with the given fields, using the allocation object to select the node and additional allocations if specified.

Fields

  • name: the name of the server
  • description (optional): the description of the server
  • external_id (optional): an external identifier for the server
  • user: the ID of the user the server will belong to
  • egg: the ID of the egg to use for the server
  • docker_image: the docker image to use for the server
  • startup: the startup command for the server
  • oom_disabled: whether the OOM killer should be disabled for the server
  • limits: an object containing the server limits
  • feature_limits: an object containing the server feature limits
  • allocation: an object containing allocation data including where the server will be created
  • start_on_completion: whether the server should start once installed
server = app.create_server(
  name: "crystal bot",
  user: 5,
  egg: 30,
  docker_image: "ghcr.io/parkervcp/yolks:crystal_1.6",
  startup: %(crystal run {{CRYSTAL_FILE}}}),
  environment: {"USER_UPLOAD" => false, "AUTO_UPDATE" => false, "CRYSTAL_FILE" => "src/main.cr"},
  limits: Ptero::Models::Limits.new(memory: 1024, disk: 1024, swap: 0, cpu: 100, io: 500),
  feature_limits: Ptero::Models::FeatureLimits.new(0, 0, 0),
  allocation: Ptero::Models::AllocationData.new(1),
  start_on_completion: false,
) # => Ptero::Models::AppServer(@id=7, @external_id=nil, @uuid="...", ...)

[View source]
def create_server(*, name : String, description : String | Nil = nil, external_id : String | Nil = nil, user : Int32, egg : Int32, docker_image : String, startup : String, environment : Hash(String, String | Int32 | Bool | Nil), skip_scripts : Bool, oom_disabled : Bool, limits : Models::Limits, feature_limits : Models::FeatureLimits, deploy : Models::DeployData, start_on_completion : Bool) : Models::AppServer #

Creates a user on the panel with the given fields, using the deploy object to find node suitable to deploy the server onto.

Fields

  • name: the name of the server
  • description (optional): the description of the server
  • external_id (optional): an external identifier for the server
  • user: the ID of the user the server will belong to
  • egg: the ID of the egg to use for the server
  • docker_image: the docker image to use for the server
  • startup: the startup command for the server
  • oom_disabled: whether the OOM killer should be disabled for the server
  • limits: an object containing the server limits
  • feature_limits: an object containing the server feature limits
  • deploy: an object containing deployment data including location and port information
  • start_on_completion: whether the server should start once installed
server = app.create_server(
  name: "crystal bot",
  user: 5,
  egg: 30,
  docker_image: "ghcr.io/parkervcp/yolks:crystal_1.6",
  startup: %(crystal run {{CRYSTAL_FILE}}}),
  environment: {"USER_UPLOAD" => false, "AUTO_UPDATE" => false, "CRYSTAL_FILE" => "src/main.cr"},
  limits: Ptero::Models::Limits.new(memory: 1024, disk: 1024, swap: 0, cpu: 100, io: 500),
  feature_limits: Ptero::Models::FeatureLimits.new(0, 0, 0),
  deploy: Ptero::Models::DeployData.new([2, 3], ["5000-5030"], false),
  start_on_completion: false,
) # => Ptero::Models::AppServer(@id=7, @external_id=nil, @uuid="...", ...)

[View source]
def create_user(*, username : String, email : String, first_name : String, last_name : String, root_admin : Bool, language : String | Nil = nil, external_id : String | Nil = nil, password : String | Nil = nil) : Models::User #

Creates a user on the panel with the given fields.

Fields

  • username: the username for the user
  • email: the email for the user
  • first_name: the first name of the user
  • last_name: the last name of the user
  • root_admin: whether the user should have administrative privileges
  • language (optional): the language or locale for the user
  • external_id (optional): an external identifier for the user
  • password (optional): the password for the user
user = app.create_user(
  username: "example",
  email: "[email protected]",
  first_name: "example",
  last_name: "user",
  root_admin: false
)
pp user # => Ptero::Models::User(
#  @created_at=2022-01-01 16:04:03.0 +00:00,
#  @email="[email protected]",
#  @external_id=nil,
#  @first_name="example",
#  @id=7,
#  @language="en",
#  @last_name="user",
#  @root_admin=false,
#  @two_factor=false,
#  @updated_at=2022-01-01 16:04:03.0 +00:00,
#  @username="example",
#  @uuid="530d7e97-5a35-40b4-a0a8-68ea487bd384")

[View source]
def delete_node(id : Int32) : Nil #

Deletes a node by its ID. Note that this will not work if there are servers on the node.


[View source]
def delete_server(id : Int32, *, with_force : Bool = false) : Nil #

Deletes a server by its ID.


[View source]
def delete_user(id : Int32) : Nil #

Deletes a user by its ID.


[View source]
def get_all_nodes(*, include includes : Array(String) | Nil = nil) : Array(Models::Node) #

Iterates over all pages from the API and returns an array of all the nodes in the panel.

Parameters

  • include: additional resources to include in the response

[View source]
def get_all_servers(*, include includes : Array(String) | Nil = nil) : Array(Models::AppServer) #

Iterates over all pages from the API and returns an array of all the servers in the panel.

Parameters

  • include: additional resources to include in the response

[View source]
def get_all_users(*, include includes : Array(String) | Nil = nil) : Array(Models::User) #

Iterates over all pages from the API and returns an array of all the users in the panel.

Parameters

  • include: additional resources to include in the response

[View source]
def get_node(id : Int32, *, include includes : Array(String) | Nil = nil) : Models::Node #

Gets a specific node by its ID.

Parameters

  • include: additional resources to include in the response

[View source]
def get_node_configuration(id : Int32) : Models::NodeConfiguration #

Gets the configuration structure for a specific node.


[View source]
def get_nodes(*, page : Int32 | Nil = nil, per_page : Int32 | Nil = nil, filter : Tuple(String, String) | Nil = nil, include includes : Array(String) | Nil = nil, sort : String | Nil = nil) : Array(Models::Node) #

Gets a list of nodes from the panel with the specified query parameters (if set).

Parameters

  • page: the page number to fetch from (default is 1)
  • per_page: the number of node objects to return (default is 50).
  • filter: an argument tuple to filter nodes from, the first being the field and the second being the value to query
  • include: additional resources to include in the response
  • sort: an argument to sort nodes in the response by

[View source]
def get_server(id : String) : Models::AppServer #

Gets a specific server by its external identifier.


[View source]
def get_server(id : Int32, *, include includes : Array(String) | Nil = nil) : Models::AppServer #

Gets a specific server by its ID.

Parameters

  • include: additional resources to include in the response

[View source]
def get_servers(*, page : Int32 | Nil = nil, per_page : Int32 | Nil = nil, filter : Tuple(String, String) | Nil = nil, include includes : Array(String) | Nil = nil, sort : String | Nil = nil) : Array(Models::AppServer) #

Gets a list of servers from the panel with the specified query parameters (if set).

Parameters

  • page: the page number to fetch from (default is 1)
  • per_page: the number of user objects to return (default is 50).
  • filter: an argument tuple to filter servers from, the first being the field and the second being the value to query
  • include: additional resources to include in the response
  • sort: an argument to sort servers in the response by

[View source]
def get_user(id : String) : Models::User #

Gets a specific user by its external identifier.


[View source]
def get_user(id : Int32, *, include includes : Array(String) | Nil = nil) : Models::User #

Gets a specific user by its ID.

Parameters

  • include: additional resources to include in the response

[View source]
def get_users(*, page : Int32 | Nil = nil, per_page : Int32 | Nil = nil, filter : Tuple(String, String) | Nil = nil, include includes : Array(String) | Nil = nil, sort : String | Nil = nil) : Array(Models::User) #

Gets a list of users from the panel with the specified query parameters (if set).

Parameters

  • page: the page number to fetch from (default is 1)
  • per_page: the number of user objects to return (default is 50).
  • filter: an argument tuple to filter users from, the first being the field and the second being the value to query
  • include: additional resources to include in the response
  • sort: an argument to sort users in the response by

[View source]
def key : String #

[View source]
def reinstall_server(id : Int32) : Nil #

Triggers the reinstall process for a specified server.


[View source]
def resolve_error(ex : Crest::RequestFailed) : NoReturn #

Resolves a library-specific error from a failed HTTP request (error response).


[View source]
def resolve_query(page : Int32 | Nil, per_page : Int32 | Nil, filter : Tuple(String, String) | Nil, includes : Array(String) | Nil, sort : String | Nil) : String #

Resolves a query string from the given parameters. This function applies its own validation rules for certain arguments silently instead of raising an exception.

app.resolve_query(per_page: 20, include: ["foo", "bar"]) # => "per_page=20&include=foo,bar"
app.resolve_query(page: 0, per_page: 150)                # => "page=1&per_page=100"

[View source]
def rest : Crest::Resource #

[View source]
def suspend_server(id : Int32) : Nil #

Suspends a specified server.


[View source]
def unsuspend_server(id : Int32) : Nil #

Unsuspends a specified server.


[View source]
def update_node(id : Int32, *, name : String | Nil = nil, description : String | Nil = nil, location_id : Int32 | Nil = nil, public : Int32 | Nil = nil, fqdn : String | Nil = nil, scheme : String | Nil = nil, behind_proxy : Bool | Nil = nil, memory : Int32 | Nil = nil, memory_overallocate : Int32 | Nil = nil, disk : Int32 | Nil = nil, disk_overallocate : Int32 | Nil = nil, daemon_base : String | Nil = nil, daemon_sftp : Int32 | Nil = nil, daemon_listen : Int32 | Nil = nil, maintenance_mode : Bool | Nil = nil, upload_size : Int32 | Nil = nil) : Models::Node #

Updates a node specified by its ID with the given fields (same as the fields for #create_node). Any fields that aren't specified will be filled with the existing value from the panel.


[View source]
def update_server_build(id : Int32, *, allocation_id : Int32 | Nil = nil, oom_disabled : Bool | Nil = nil, limits : Limits | Nil = nil, feature_limits : FeatureLimits | Nil = nil, add_allocations : Set(Int32) = Set(Int32).new, remove_allocations : Set(Int32) = Set(Int32).new) : Models::AppServer #

Updates the build configuration for a specified server. Fields that are not specified will fallback to their current values if set.

Fields

  • allocation_id (optional): the ID of the primary allocation the server should use
  • oom_disabled (optional): whether the OOM killer should be disabled
  • limits (optional): the limits of the server
  • feature_limits (optional): the feature limits of the server
  • add_allocations (optional): a set of allocations to add to the server
  • remove_allocations (optional): a set of allocations to remove from the server

[View source]
def update_server_details(id : Int32, *, external_id : String | Nil = nil, name : String | Nil = nil, description : String | Nil = nil, user : Int32 | Nil = nil) : Models::AppServer #

Updates a specified server's details. Fields that are not specified will fallback to their current values if set.

Fields

  • external_id (optional): the external identifier for the server, set to an empty string to remove it
  • name (optional): the name of the server
  • description (optional): a description of the server, set to an empty string to remove it
  • user (optional): the ID of the server owner

[View source]
def update_server_startup(id : Int32, *, startup : String | Nil = nil, environment : Hash(String, String | Int32 | Bool | Nil) | Nil = nil, egg : Int32 | Nil = nil, image : String | Nil = nil) : Models::AppServer #

Updates a specified servers' startup configuration. For environment variables, unset fields will be replaced with the default values from the panel if set.

Fields

  • startup (optional): the startup command for the server
  • environment (optional): a hash of environment variables to set for the server
  • egg (optional): the ID of the egg to use for the server
  • image (optional): the docker image to use for the server

[View source]
def update_user(id : Int32, *, username : String | Nil = nil, email : String | Nil = nil, first_name : String | Nil = nil, last_name : String | Nil = nil, root_admin : Bool | Nil = nil, language : String | Nil = nil, external_id : String | Nil = nil, password : String | Nil = nil) : Models::User #

Updates a user specified by its ID with the given fields (same as the fields for #create_user). Any fields that aren't specified will be filled with the existing value from the panel.


[View source]
def url : String #

[View source]