fly_io 0.1.0

data/contracts/sources/network-policies.html.markerb

@@ -0,0 +1,142 @@
+---
+title: Network Policies
+layout: docs
+order: 25
+nav: machines
+---
+
+Network policies let you control traffic to and from your Machines. You can use policies to allow or restrict ingress and egress on specific ports and protocols. This is useful when you're running untrusted code or want to lock down what traffic is allowed.
+
+<div class="callout">
+Network policies only apply to traffic directly to and from Machines. They do not affect traffic routed through the Fly Proxy.
+
+</div>
+
+## How it works
+
+A network policy contains:
+
+* A `selector` to match which Machines the policy applies to.
+* A list of `rules` for ingress or egress, specifying allowed ports and protocols.
+
+Once you create a rule for a direction (ingress or egress), the default for that direction becomes "deny all." Only explicitly allowed traffic will be permitted.
+
+## Restricting egress traffic to HTTP/HTTPS
+
+For example, if you're running an app that should only make outbound HTTP and HTTPS requests, you can create a policy like this:
+
+```sh
+curl --location 'https://api.machines.dev/v1/apps/my-app-name/network_policies' \
+  --header 'Authorization: Bearer <FLY_API_TOKEN>' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "name": "specific-egress",
+    "selector": {
+      "all": true
+    },
+    "rules": [
+      {
+        "action": "allow",
+        "direction": "egress",
+        "ports": [
+          { "protocol": "tcp", "port": 80 },
+          { "protocol": "tcp", "port": 443 }
+        ]
+      }
+    ]
+  }'
+```
+
+Replace `<FLY_API_TOKEN>` and `my-app-name` with your actual values.
+
+## Selectors
+
+Selectors determine which Machines your network policy applies to. You can target Machines using one or more of the following methods:
+
+### All Machines in an app
+
+To apply a policy to every Machine in your app:
+
+```json
+{ "all": true }
+```
+
+### Specific Machine IDs
+
+To target individual Machines by their unique identifiers:
+
+```json
+{ "machines": [ { "id": "abc" }, { "id": "def" } ] }
+```
+
+### Metadata matching
+
+To select Machines based on their metadata attributes:
+
+```json
+{ "metadata": { "role": "web", "env": "production" } }
+```
+These selection methods can be combined to create more precise targeting rules that match Machines satisfying all specified criteria.
+
+## Rules
+
+Each rule has:
+
+* `action`: Only `allow` is supported.
+* `direction`: Either `ingress` or `egress`.
+* `ports`: A list of port and protocol objects.
+
+Example:
+
+```json
+{
+  "action": "allow",
+  "direction": "egress",
+  "ports": [
+    { "protocol": "tcp", "port": 443 }
+  ]
+}
+```
+
+Once a rule is defined, all other traffic in that direction is denied by default.
+
+## API summary
+
+### Create or update a policy
+
+```http
+POST /v1/apps/<app_name>/network_policies
+```
+
+Request body:
+
+```json
+{
+  "name": "policy-name",
+  "id": "optional-policy-id",  
+  "selector": { ... },
+  "rules": [ ... ]
+}
+```
+Include the `id` field to update an existing policy.
+
+### List policies
+
+```http
+GET /v1/apps/<app_name>/network_policies/
+```
+
+### Delete a policy
+
+```http
+DELETE /v1/apps/<app_name>/network_policies/<policy_id>
+```
+
+## Troubleshooting
+
+* After creating or updating a policy, restart or redeploy the Machines for changes to take effect.
+* Use direct IP addresses (not hostnames) to test blocked traffic to avoid DNS masking.
+* Make sure your `selector` is correct and matches the Machines you expect.
+* If traffic is still allowed unexpectedly, check if it's going through the Fly Proxy.
+
+

data/docs/API.md

@@ -0,0 +1,149 @@
+# Generated Fly API reference
+
+Machines metadata is generated from `https://docs.machines.dev/openapi.json` (SHA-256 `9e6a180c40a38bf20b72a8577a8cd93866f47882627b608af753cc4c22f7758f`).
+This file lists 98 Machines OpenAPI operations, 3 Network Policies
+documentation-derived operations, and 7 Prometheus endpoint families. GraphQL's
+experimental generated-operation adapter is inventoried separately in `generated/graphql_operations.json`.
+Do not edit this file by hand.
+
+## Apps
+
+- `GET /v1/apps` → `client.apps.list` (`Apps_list`)
+- `POST /v1/apps` → `client.apps.create` (`Apps_create`)
+- `GET /v1/apps/{app_name}` → `client.apps.get` (`Apps_show`)
+- `DELETE /v1/apps/{app_name}` → `client.apps.destroy` (`Apps_delete`)
+- `POST /v1/apps/{app_name}/deploy_token` → `client.apps.create_deploy_token` (`App_create_deploy_token`)
+- `GET /v1/apps/{app_name}/ip_assignments` → `client.apps.list_ip_assignments` (`App_IPAssignments_list`)
+- `POST /v1/apps/{app_name}/ip_assignments` → `client.apps.create_ip_assignment` (`App_IPAssignments_create`)
+- `DELETE /v1/apps/{app_name}/ip_assignments/{ip}` → `client.apps.delete_ip_assignment` (`App_IPAssignments_delete`)
+
+## Machines
+
+- `GET /v1/apps/{app_name}/machines` → `client.machines.list` (`Machines_list`)
+- `POST /v1/apps/{app_name}/machines` → `client.machines.create` (`Machines_create`)
+- `GET /v1/apps/{app_name}/machines/{machine_id}` → `client.machines.get` (`Machines_show`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}` → `client.machines.update` (`Machines_update`)
+- `DELETE /v1/apps/{app_name}/machines/{machine_id}` → `client.machines.destroy` (`Machines_delete`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/cordon` → `client.machines.cordon` (`Machines_cordon`)
+- `GET /v1/apps/{app_name}/machines/{machine_id}/events` → `client.machines.events` (`Machines_list_events`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/exec` → `client.machines.execute` (`Machines_exec`)
+- `GET /v1/apps/{app_name}/machines/{machine_id}/lease` → `client.machines.lease` (`Machines_show_lease`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/lease` → `client.machines.create_lease` (`Machines_create_lease`)
+- `DELETE /v1/apps/{app_name}/machines/{machine_id}/lease` → `client.machines.release_lease` (`Machines_release_lease`)
+- `GET /v1/apps/{app_name}/machines/{machine_id}/memory` → `client.machines.memory` (`Machines_get_memory`)
+- `PUT /v1/apps/{app_name}/machines/{machine_id}/memory` → `client.machines.set_memory_limit` (`Machines_set_memory_limit`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/memory/reclaim` → `client.machines.reclaim_memory` (`Machines_reclaim_memory`)
+- `GET /v1/apps/{app_name}/machines/{machine_id}/metadata` → `client.machines.metadata` (`Machines_show_metadata`)
+- `PUT /v1/apps/{app_name}/machines/{machine_id}/metadata` → `client.machines.replace_metadata` (`Machines_update_metadata`)
+- `PATCH /v1/apps/{app_name}/machines/{machine_id}/metadata` → `client.machines.update_metadata` (`Machines_update_metadata`)
+- `GET /v1/apps/{app_name}/machines/{machine_id}/metadata/{key}` → `client.machines.get_metadata` (`Machines_get_metadata_key`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/metadata/{key}` → `client.machines.set_metadata` (`Machines_upsert_metadata`)
+- `DELETE /v1/apps/{app_name}/machines/{machine_id}/metadata/{key}` → `client.machines.delete_metadata` (`Machines_delete_metadata`)
+- `GET /v1/apps/{app_name}/machines/{machine_id}/ps` → `client.machines.processes` (`Machines_list_processes`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/restart` → `client.machines.restart` (`Machines_restart`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/signal` → `client.machines.signal` (`Machines_signal`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/start` → `client.machines.start` (`Machines_start`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/stop` → `client.machines.stop` (`Machines_stop`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/suspend` → `client.machines.suspend` (`Machines_suspend`)
+- `POST /v1/apps/{app_name}/machines/{machine_id}/uncordon` → `client.machines.uncordon` (`Machines_uncordon`)
+- `GET /v1/apps/{app_name}/machines/{machine_id}/versions` → `client.machines.versions` (`Machines_list_versions`)
+- `GET /v1/apps/{app_name}/machines/{machine_id}/wait` → `client.machines.wait` (`Machines_wait`)
+
+## Metrics
+
+- `GET /prometheus/{org_slug}/api/v1/query` → `client.metrics.query` (`Prometheus_query`)
+- `GET /prometheus/{org_slug}/api/v1/query_range` → `client.metrics.query_range` (`Prometheus_query_range`)
+- `GET /prometheus/{org_slug}/api/v1/series` → `client.metrics.series` (`Prometheus_series`)
+- `GET /prometheus/{org_slug}/api/v1/labels` → `client.metrics.labels` (`Prometheus_labels`)
+- `GET /prometheus/{org_slug}/api/v1/label/{label_name}/values` → `client.metrics.label_values` (`Prometheus_label_values`)
+- `GET /prometheus/{org_slug}/api/v1/status/tsdb` → `client.metrics.tsdb` (`Prometheus_tsdb`)
+- `GET /prometheus/{org_slug}/federate` → `client.metrics.federate` (`Prometheus_federate`)
+
+## Network Policies
+
+- `POST /v1/apps/{app_name}/network_policies` → `client.network_policies.upsert` (`NetworkPolicies_upsert`)
+- `GET /v1/apps/{app_name}/network_policies/` → `client.network_policies.list` (`NetworkPolicies_list`)
+- `DELETE /v1/apps/{app_name}/network_policies/{policy_id}` → `client.network_policies.delete` (`NetworkPolicies_delete`)
+
+## Organizations
+
+- `GET /v1/orgs/{org_slug}/machines` → `client.organizations.list_machines` (`Machines_org_list`)
+- `GET /v1/orgs/{org_slug}/volumes` → `client.organizations.list_volumes` (`Volumes_org_list`)
+
+## Platform
+
+- `POST /v1/platform/placements` → `client.platform.placements` (`Platform_placements_post`)
+- `GET /v1/platform/regions` → `client.platform.regions` (`Platform_regions_get`)
+
+## Postgres Clusters
+
+- `GET /v1/postgres` → `client.postgres_clusters.list` (`Postgres_list`)
+- `POST /v1/postgres` → `client.postgres_clusters.create` (`Postgres_create`)
+- `GET /v1/postgres/{postgres_cluster_id}` → `client.postgres_clusters.show` (`Postgres_show`)
+- `DELETE /v1/postgres/{postgres_cluster_id}` → `client.postgres_clusters.delete` (`Postgres_delete`)
+- `POST /v1/postgres/{postgres_cluster_id}/attachments` → `client.postgres_clusters.attachments_create` (`Postgres_attachments_create`)
+- `DELETE /v1/postgres/{postgres_cluster_id}/attachments/{app_name}` → `client.postgres_clusters.attachments_delete` (`Postgres_attachments_delete`)
+- `GET /v1/postgres/{postgres_cluster_id}/backups` → `client.postgres_clusters.backups_list` (`Postgres_backups_list`)
+- `POST /v1/postgres/{postgres_cluster_id}/backups` → `client.postgres_clusters.backups_create` (`Postgres_backups_create`)
+- `GET /v1/postgres/{postgres_cluster_id}/databases` → `client.postgres_clusters.databases_list` (`Postgres_databases_list`)
+- `POST /v1/postgres/{postgres_cluster_id}/databases` → `client.postgres_clusters.databases_create` (`Postgres_databases_create`)
+- `DELETE /v1/postgres/{postgres_cluster_id}/databases/{database_name}` → `client.postgres_clusters.databases_delete` (`Postgres_databases_delete`)
+- `GET /v1/postgres/{postgres_cluster_id}/databases/{database_name}/extensions` → `client.postgres_clusters.extensions_list` (`Postgres_extensions_list`)
+- `POST /v1/postgres/{postgres_cluster_id}/databases/{database_name}/extensions` → `client.postgres_clusters.extensions_enable` (`Postgres_extensions_enable`)
+- `DELETE /v1/postgres/{postgres_cluster_id}/databases/{database_name}/extensions/{extension_name}` → `client.postgres_clusters.extensions_disable` (`Postgres_extensions_disable`)
+- `POST /v1/postgres/{postgres_cluster_id}/fork` → `client.postgres_clusters.fork` (`Postgres_fork`)
+- `POST /v1/postgres/{postgres_cluster_id}/restore` → `client.postgres_clusters.restore` (`Postgres_restore`)
+- `GET /v1/postgres/{postgres_cluster_id}/users` → `client.postgres_clusters.users_list` (`Postgres_users_list`)
+- `POST /v1/postgres/{postgres_cluster_id}/users` → `client.postgres_clusters.users_create` (`Postgres_users_create`)
+- `DELETE /v1/postgres/{postgres_cluster_id}/users/{username}` → `client.postgres_clusters.users_delete` (`Postgres_users_delete`)
+- `PATCH /v1/postgres/{postgres_cluster_id}/users/{username}` → `client.postgres_clusters.users_update_role` (`Postgres_users_update_role`)
+- `GET /v1/postgres/{postgres_cluster_id}/users/{username}/credentials` → `client.postgres_clusters.users_credentials` (`Postgres_users_credentials`)
+- `POST /v1/postgres/{postgres_cluster_id}/users/{username}/rotate_password` → `client.postgres_clusters.users_rotate_password` (`Postgres_users_rotate_password`)
+
+## Secrets
+
+- `GET /v1/apps/{app_name}/secretkeys` → `client.secrets.list_keys` (`Secretkeys_list`)
+- `GET /v1/apps/{app_name}/secretkeys/{secret_name}` → `client.secrets.get_key` (`Secretkey_get`)
+- `POST /v1/apps/{app_name}/secretkeys/{secret_name}` → `client.secrets.set_key` (`Secretkey_set`)
+- `DELETE /v1/apps/{app_name}/secretkeys/{secret_name}` → `client.secrets.delete_key` (`Secretkey_delete`)
+- `POST /v1/apps/{app_name}/secretkeys/{secret_name}/decrypt` → `client.secrets.decrypt_key` (`Secretkey_decrypt`)
+- `POST /v1/apps/{app_name}/secretkeys/{secret_name}/encrypt` → `client.secrets.encrypt_key` (`Secretkey_encrypt`)
+- `POST /v1/apps/{app_name}/secretkeys/{secret_name}/generate` → `client.secrets.generate_key` (`Secretkey_generate`)
+- `POST /v1/apps/{app_name}/secretkeys/{secret_name}/sign` → `client.secrets.sign_key` (`Secretkey_sign`)
+- `POST /v1/apps/{app_name}/secretkeys/{secret_name}/verify` → `client.secrets.verify_key` (`Secretkey_verify`)
+- `GET /v1/apps/{app_name}/secrets` → `client.secrets.list` (`Secrets_list`)
+- `POST /v1/apps/{app_name}/secrets` → `client.secrets.update` (`Secrets_update`)
+- `GET /v1/apps/{app_name}/secrets/{secret_name}` → `client.secrets.get` (`Secret_get`)
+- `POST /v1/apps/{app_name}/secrets/{secret_name}` → `client.secrets.set` (`Secret_create`)
+- `DELETE /v1/apps/{app_name}/secrets/{secret_name}` → `client.secrets.delete` (`Secret_delete`)
+
+## TLS Certificates
+
+- `GET /v1/apps/{app_name}/certificates` → `client.certificates.list` (`App_Certificates_list`)
+- `POST /v1/apps/{app_name}/certificates/acme` → `client.certificates.request_acme` (`App_Certificates_acme_create`)
+- `POST /v1/apps/{app_name}/certificates/custom` → `client.certificates.upload_custom` (`App_Certificates_custom_create`)
+- `GET /v1/apps/{app_name}/certificates/{hostname}` → `client.certificates.get` (`App_Certificates_show`)
+- `DELETE /v1/apps/{app_name}/certificates/{hostname}` → `client.certificates.remove` (`App_Certificates_delete`)
+- `DELETE /v1/apps/{app_name}/certificates/{hostname}/acme` → `client.certificates.remove_acme` (`App_Certificates_acme_delete`)
+- `POST /v1/apps/{app_name}/certificates/{hostname}/check` → `client.certificates.check` (`App_Certificates_check`)
+- `DELETE /v1/apps/{app_name}/certificates/{hostname}/custom` → `client.certificates.remove_custom` (`App_Certificates_custom_delete`)
+
+## Tokens
+
+- `POST /v1/tokens/authenticate` → `client.tokens.authenticate` (`Tokens_authenticate`)
+- `POST /v1/tokens/authorize` → `client.tokens.authorize` (`Tokens_authorize`)
+- `GET /v1/tokens/current` → `client.tokens.current` (`CurrentToken_show`)
+- `POST /v1/tokens/kms` → `client.tokens.request_kms` (`Tokens_request_Kms`)
+- `POST /v1/tokens/oidc` → `client.tokens.request_oidc` (`Tokens_request_OIDC`)
+
+## Volumes
+
+- `GET /v1/apps/{app_name}/volumes` → `client.volumes.list` (`Volumes_list`)
+- `POST /v1/apps/{app_name}/volumes` → `client.volumes.create` (`Volumes_create`)
+- `GET /v1/apps/{app_name}/volumes/{volume_id}` → `client.volumes.get` (`Volumes_get_by_id`)
+- `PUT /v1/apps/{app_name}/volumes/{volume_id}` → `client.volumes.update` (`Volumes_update`)
+- `DELETE /v1/apps/{app_name}/volumes/{volume_id}` → `client.volumes.destroy` (`Volume_delete`)
+- `PUT /v1/apps/{app_name}/volumes/{volume_id}/extend` → `client.volumes.extend` (`Volumes_extend`)
+- `GET /v1/apps/{app_name}/volumes/{volume_id}/snapshots` → `client.volumes.list_snapshots` (`Volumes_list_snapshots`)
+- `POST /v1/apps/{app_name}/volumes/{volume_id}/snapshots` → `client.volumes.create_snapshot` (`createVolumeSnapshot`)
+

data/docs/SURFACES.md

@@ -0,0 +1,60 @@
+# Fly.io public API surface inventory
+
+Retrieved 2026-08-26. The machine-readable source is
+[`contracts/public_surface_inventory.json`](../contracts/public_surface_inventory.json).
+
+## Supported surfaces
+
+| Surface | Base URL | Stability | Authoritative contract/evidence | Count | Ruby coverage |
+|---|---|---|---|---:|---|
+| Machines REST | `https://api.machines.dev` | Public documented | OpenAPI 3.0.1, `https://docs.machines.dev/openapi.json`, SHA-256 `9e6a180c40a38bf20b72a8577a8cd93866f47882627b608af753cc4c22f7758f` | 68 paths / 98 operations / 173 schemas | 98 generated resource methods and operation-ID adapter; 173 typed models |
+| Network Policies REST | `https://api.machines.dev` | Public documented; no formal stability label | Official docs revision `1e8cac5f0fd7a82e66e3b01ece3a10a8ecb2b7e3`, source SHA-256 `fa64b69db56beb1da2de60e3ff91820b628a1238a120d103c2f3bae16e2fcc1f` | 3 operations | `client.network_policies`; responses raw because upstream documents none |
+| Control-plane GraphQL | `https://api.fly.io/graphql` | **Internal/experimental; explicitly no stability guarantee** | flyctl revision `1f906765dee8e973f6d1dd8fff65b58212e7b425`; evidence schema SHA-256 `2f1a1d0f2f8940277e5e14002c78cb4f6404b3ea1ce9d0999d4d3b65c52f9480` | 39 query + 141 mutation schema root fields; 29 flyctl + 85 fly-go + 3 official observed documents | Raw first-class `GraphQLClient`; 117-operation experimental generated adapter; opt-in introspection |
+| Prometheus metrics | `https://api.fly.io/prometheus/{org_slug}/` | Stable standard data API with qualified compatibility; not control-plane | Official docs revision `1e8cac5f0fd7a82e66e3b01ece3a10a8ecb2b7e3`, source SHA-256 `e22d7b34406b16c2ea75eed6cd92c51ec07d166963155623557295ef24f67e9f`; Prometheus/VictoriaMetrics contracts | 7 endpoint families | `client.metrics` typed response envelope and federation text |
+
+Machines families are Apps (8), TLS Certificates (8), Machines (29), Secrets (14), Volumes (8), Organizations (2),
+Platform (2), Postgres Clusters (22), and Tokens (5). Network Policies adds its own family outside OpenAPI.
+
+## Authentication decision
+
+The official Machines guide specifies `Bearer`; the generated reference says `FlyV1` in prose but uses `Bearer` in
+its curl example. flyctl selects schemes by token kind. The gem therefore maps raw tokens to `Bearer` and accepts an
+explicit preformatted authorization value or explicit `:fly_v1` mode. It never guesses from token contents.
+
+## Audited exclusions
+
+| Surface | Decision and reason |
+|---|---|
+| Extensions partner OAuth/webhooks | Partner-gated, prose-only integration requiring Fly-issued credentials; not a general account control-plane API. The audit records 4 prose operations but the gem does not imply public availability. |
+| flyctl UIEX REST (`https://api.fly.io/api/v1`) | 52 current internal call sites, with no official public documentation or schema. Excluded rather than presenting observed implementation details as stable. |
+| Tigris S3 | Adjacent beta data plane governed by the external S3 contract and separate credentials. |
+| `registry.fly.io` | Adjacent image data plane accessed through Docker/OCI tooling and its external distribution contract. |
+
+## Known upstream gaps and follow-up checks
+
+- `Machines_update_metadata` is duplicated for PUT and PATCH. Coverage identity is method + path + operation ID.
+- OpenAPI has no security scheme and omits several used tags from its top-level declaration.
+- Network Policies is absent from OpenAPI; its guide gives no response status/schema and shows a trailing slash only
+  for list. The committed documentation snapshot makes this ambiguity reviewable.
+- Fly’s GraphQL schema is manually copied into flyctl from a private repository. It is evidence, never a stable
+  contract. Refresh all three GraphQL inventories when flyctl or fly-go revisions change.
+- Fly describes Prometheus support as “most common” compatible endpoints; `api:check` asserts the seven listed
+  families, while semantics stay delegated to Prometheus/VictoriaMetrics.
+
+Run `bundle exec rake api:check` offline for all committed contracts and `bundle exec rake api:fetch_check` to compare
+the Machines snapshot with the live OpenAPI URL.
+
+## Authoritative starting links
+
+- [Machines API overview](https://fly.io/docs/machines/api/)
+- [Machines OpenAPI JSON](https://docs.machines.dev/openapi.json)
+- [Generated Machines reference](https://docs.machines.dev/)
+- [Connection, authentication, statuses, and rate limits](https://fly.io/docs/machines/api/working-with-machines-api)
+- [Apps resource](https://fly.io/docs/machines/api/apps-resource)
+- [Machines resource](https://fly.io/docs/machines/api/machines-resource)
+- [Volumes resource](https://fly.io/docs/machines/api/volumes-resource)
+- [Certificates resource](https://fly.io/docs/machines/api/certificates-resource)
+- [Tokens resource](https://fly.io/docs/machines/api/tokens-resource)
+- [REST and GraphQL stability guidance](https://fly.io/docs/machines/guides-examples/managing-machines-with-the-api)
+- [Network Policies](https://fly.io/docs/machines/guides-examples/network-policies)
+- [Prometheus metrics](https://fly.io/docs/monitoring/metrics)

data/lib/fly_io/client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module FlyIO
+  class Client
+    RESOURCE_NAMES = %w[apps certificates machines secrets volumes organizations platform postgres_clusters tokens
+                        network_policies metrics].freeze
+
+    attr_reader :configuration, :transport
+
+    def initialize(configuration = nil, **options)
+      if configuration && !options.empty?
+        raise ConfigurationError, "provide a Configuration or keyword options, not both"
+      end
+
+      @configuration = configuration || Configuration.new(**options)
+      unless @configuration.is_a?(Configuration)
+        raise ConfigurationError,
+              "configuration must be a FlyIO::Configuration"
+      end
+
+      @transport = Transport.new(@configuration)
+      @metrics_transport = Transport.new(@configuration.with(base_url: @configuration.metrics_url))
+      @resources = RESOURCE_NAMES.to_h do |name|
+        [name, Resources.class_for(name).new(self)]
+      end.freeze
+      freeze
+    end
+
+    RESOURCE_NAMES.each do |name|
+      define_method(name) { @resources.fetch(name) }
+    end
+
+    def graphql
+      GraphQLClient.new(configuration)
+    end
+
+    def transport_for(operation)
+      operation.surface == "prometheus_metrics" ? @metrics_transport : transport
+    end
+
+    def request(method:, path:, path_params: {}, query: {}, headers: {}, body: FlyIO::UNSET,
+                content_type: "application/json", accept: "application/json", retry_unsafe: nil, timeout: nil)
+      transport.request(method: method, path: path, path_params: path_params, query: query, headers: headers,
+                        body: body, content_type: content_type, accept: accept, retry_unsafe: retry_unsafe, timeout: timeout)
+    end
+
+    def operation(operation_id, method: nil, path: nil, **arguments)
+      operation = OperationRegistry.fetch(operation_id, method: method, path: path)
+      @resources.fetch(operation.ruby_resource).operation(operation_id, method: method, path: path, **arguments)
+    end
+  end
+end

data/lib/fly_io/configuration.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module FlyIO
+  class Configuration
+    DEFAULT_BASE_URL = "https://api.machines.dev"
+    DEFAULT_GRAPHQL_URL = "https://api.fly.io/graphql"
+
+    ATTRIBUTES = %i[
+      base_url graphql_url metrics_url authorization_value open_timeout read_timeout write_timeout request_timeout
+      proxy user_agent max_retries base_retry_interval max_retry_interval retry_jitter logger adapter
+      sleeper random retry_unsafe introspection
+    ].freeze
+
+    attr_reader(*ATTRIBUTES)
+
+    def initialize(token: nil, authorization: nil, authorization_mode: :bearer,
+                   base_url: DEFAULT_BASE_URL, graphql_url: DEFAULT_GRAPHQL_URL, metrics_url: "https://api.fly.io",
+                   open_timeout: 10, read_timeout: 30, write_timeout: 30, request_timeout: nil,
+                   proxy: nil, user_agent: "fly_io/#{FlyIO::VERSION}", max_retries: 2,
+                   base_retry_interval: 0.25, max_retry_interval: 5.0, retry_jitter: 0.25,
+                   logger: nil, adapter: nil, sleeper: ->(seconds) { sleep(seconds) },
+                   random: Random.new, retry_unsafe: false, introspection: false)
+      @base_url = normalize_url(base_url, "base_url")
+      @graphql_url = normalize_url(graphql_url, "graphql_url")
+      @metrics_url = normalize_url(metrics_url, "metrics_url")
+      @authorization_value = build_authorization(token, authorization, authorization_mode)
+      @open_timeout = positive_number(open_timeout, "open_timeout")
+      @read_timeout = positive_number(read_timeout, "read_timeout")
+      @write_timeout = positive_number(write_timeout, "write_timeout")
+      @request_timeout = request_timeout && positive_number(request_timeout, "request_timeout")
+      @proxy = proxy
+      @user_agent = String(user_agent).dup.freeze
+      @max_retries = Integer(max_retries)
+      @base_retry_interval = Float(base_retry_interval)
+      @max_retry_interval = Float(max_retry_interval)
+      @retry_jitter = Float(retry_jitter)
+      @logger = logger
+      @adapter = adapter
+      @sleeper = sleeper
+      @random = random
+      @retry_unsafe = retry_unsafe
+      @introspection = introspection
+      validate_retry!
+      freeze
+    end
+
+    def with(**overrides)
+      current = ATTRIBUTES.to_h { |name| [name, public_send(name)] }
+      authorization_value = current.delete(:authorization_value)
+      current[:authorization] = authorization_value
+      self.class.new(**current, **overrides)
+    end
+
+    private
+
+    def build_authorization(token, authorization, mode)
+      if token && authorization
+        raise ConfigurationError, "provide token or authorization, not both"
+      end
+
+      if authorization
+        value = String(authorization).strip
+        raise ConfigurationError, "authorization must include a scheme and value" unless value.match?(/\A\S+\s+\S+/)
+
+        return value.freeze
+      end
+
+      raw = String(token || "").strip
+      raise ConfigurationError, "token is required" if raw.empty?
+      if raw.match?(/\A(?:Bearer|FlyV1)\s+/i)
+        raise ConfigurationError,
+              "token must be raw; use authorization: for a preformatted value"
+      end
+
+      scheme = {bearer: "Bearer", fly_v1: "FlyV1"}.fetch(mode.to_sym) do
+        raise ConfigurationError, "authorization_mode must be :bearer or :fly_v1"
+      end
+      "#{scheme} #{raw}".freeze
+    end
+
+    def normalize_url(value, name)
+      uri = URI.parse(String(value))
+      raise ConfigurationError, "#{name} must be an absolute HTTP(S) URL" unless %w[http
+                                                                                    https].include?(uri.scheme) && uri.host
+      if uri.userinfo || uri.query || uri.fragment
+        raise ConfigurationError,
+              "#{name} must not contain credentials, query, or fragment"
+      end
+
+      uri.path = uri.path.sub(%r{/+\z}, "")
+      uri.to_s.freeze
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "#{name} must be a valid URL"
+    end
+
+    def positive_number(value, name)
+      number = Float(value)
+      raise ConfigurationError, "#{name} must be positive" unless number.positive?
+
+      number
+    end
+
+    def validate_retry!
+      raise ConfigurationError, "max_retries must be non-negative" if max_retries.negative?
+      raise ConfigurationError, "retry intervals and jitter must be non-negative" if [base_retry_interval,
+                                                                                      max_retry_interval, retry_jitter].any?(&:negative?)
+      return unless max_retry_interval < base_retry_interval
+
+      raise ConfigurationError,
+            "max_retry_interval must be at least base_retry_interval"
+    end
+  end
+end

data/lib/fly_io/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module FlyIO
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class ArgumentError < Error; end
+
+  class APIError < Error
+    attr_reader :status, :headers, :details, :request_id, :request
+
+    def initialize(message = nil, status: nil, headers: {}, details: nil, request_id: nil, request: nil)
+      @status = status
+      @headers = headers.freeze
+      @details = details
+      @request_id = request_id
+      @request = request
+      super(Redactor.redact(message || default_message))
+    end
+
+    private
+
+    def default_message
+      ["Fly.io API request failed", ("(HTTP #{status})" if status),
+       ("request_id=#{request_id}" if request_id)].compact.join(" ")
+    end
+  end
+
+  class AuthenticationError < APIError; end
+  class AuthorizationError < APIError; end
+  class NotFoundError < APIError; end
+  class ValidationError < APIError; end
+  class RateLimitError < APIError; end
+  class RequestTimeoutError < APIError; end
+  class ServerError < APIError; end
+  class TransportError < APIError; end
+
+  class GraphQLError < APIError
+    attr_reader :graphql_errors
+
+    def initialize(message = "Fly.io GraphQL request failed", graphql_errors: [], **)
+      @graphql_errors = Redactor.redact_object(graphql_errors)
+      super(message, details: @graphql_errors, **)
+    end
+  end
+end