Typed Fly.io Machines API Adapter
Overview
Fly.io publishes a REST API and OpenAPI reference; this workflow does not claim a provider-maintained JavaScript SDK. Generate or handwrite only a thin local adapter, keep provider fields visible, and centralize authentication, timeouts, limits, state waits, and redaction.
Prerequisites
- Chosen operations and current OpenAPI or endpoint documentation
- Runtime and HTTP client policy, schema generator decision, and error model
- Synthetic fixtures plus an authorized non-production app for contract verification
Instructions
Step 1: Freeze the contract
Record base URL, operation paths, request and response schemas, state enums, response codes, and retrieval fingerprint. Preserve unknown fields for forward compatibility.
Step 2: Define a thin transport
Centralize bearer auth, content type, request ID, timeout, retry eligibility, response parsing, and error redaction. Do not hide target app or Machine identifiers.
Step 3: Model desired and observed state
Represent Machine ID, instance version, configuration, lifecycle state, and target state separately. Require callers to reconcile before replay.
Step 4: Use the provider wait operation
After a mutation, wait for started, stopped, suspended, or destroyed with a bounded timeout and the required instance version where applicable.
Step 5: Apply rate and conflict policy
Serialize conflicting actions per identifier, use documented per-action limits, retry only eligible failures, and refresh after 409, 408, or ambiguous transport results.
Step 6: Test the adapter
Use fixture tests for every response and error class, then run an authorized read and one reversible non-production lifecycle operation with cleanup.
Authentication
Inject FLY_API_TOKEN from a secret manager and send it only as the bearer header to the documented Machines API host. Keep token scope outside the client configuration file and scrub headers and Machine config secrets from exceptions.
Tool Discipline
Use Read and Grep to inspect application configuration, deployment evidence, provider documentation, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for an approved plan, configuration, implementation, test, or redacted receipt. Do not create, deploy, scale, restart, stop, suspend, destroy, rotate, revoke, expose, or migrate live Fly.io resources without explicit operator approval.
Output
- Contract fingerprint and supported-operation matrix
- Typed adapter with transport, state, rate, conflict, and redaction policies
- Fixture and non-production contract-test receipt with cleanup state
Return the target organization, app, environment, region set, Machine or database identifiers, source-contract fingerprint, evidence, unresolved risks, rollback state, and final decision without exposing tokens, secrets, connection strings, or customer data.
Examples
A TypeScript service wraps get, update, start, stop, and wait without inventing an official SDK. It records the active instance version, waits for the documented target states, serializes actions per Machine, and preserves unknown response properties.
Error Handling
| Failure | Response |
|---|---|
| Response schema changes | Quarantine the unknown shape, preserve raw redacted evidence, update fixtures and types, and re-run contract tests. |
| Wait returns 408 | Read current Machine and instance state; do not assume the preceding mutation failed. |
| Adapter receives 401 | Stop, verify the secret reference and token scope, and never print the bearer value. |