fly_io 0.1.0

data/lib/fly_io/transport.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "time"
+require "uri"
+
+module FlyIO
+  class Transport
+    METHODS = %i[get head options post put patch delete].freeze
+    SAFE_METHODS = %i[get head options].freeze
+    RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504].freeze
+    ERROR_CLASSES = {
+      400 => ValidationError,
+      401 => AuthenticationError,
+      403 => AuthorizationError,
+      404 => NotFoundError,
+      408 => RequestTimeoutError,
+      409 => ValidationError,
+      410 => NotFoundError,
+      412 => ValidationError,
+      422 => ValidationError,
+      429 => RateLimitError
+    }.freeze
+
+    attr_reader :configuration
+
+    def initialize(configuration)
+      @configuration = configuration
+      @connection = build_connection unless configuration.adapter.respond_to?(:call)
+      freeze
+    end
+
+    def request(method:, path:, path_params: {}, query: {}, headers: {}, body: FlyIO::UNSET,
+                content_type: "application/json", accept: "application/json", retry_unsafe: nil, operation: nil,
+                timeout: nil)
+      verb = validate_method(method)
+      expanded_path = build_path(path, path_params)
+      url = absolute_url(build_url(expanded_path, query))
+      request_headers = default_headers(accept).merge(stringify_keys(headers))
+      encoded_body = encode_body(body, content_type, request_headers)
+      metadata = safe_request_metadata(verb, expanded_path, query, request_headers, body, operation)
+      attempts = 0
+
+      loop do
+        begin
+          raw_response = perform(verb, url, request_headers, encoded_body, timeout)
+        rescue Faraday::TimeoutError
+          if attempts < configuration.max_retries && retry_allowed?(verb, retry_unsafe)
+            configuration.sleeper.call(retry_delay(attempts, {}))
+            attempts += 1
+            next
+          end
+          raise RequestTimeoutError.new("Fly.io API request timed out", request: metadata)
+        rescue Faraday::ConnectionFailed, Faraday::SSLError => e
+          if attempts < configuration.max_retries && retry_allowed?(verb, retry_unsafe)
+            configuration.sleeper.call(retry_delay(attempts, {}))
+            attempts += 1
+            next
+          end
+          raise TransportError.new("Fly.io API transport failed: #{e.class}", request: metadata)
+        end
+        if retry_status?(raw_response.status, verb, retry_unsafe) && attempts < configuration.max_retries
+          delay = retry_delay(attempts, raw_response.headers)
+          attempts += 1
+          configuration.sleeper.call(delay)
+          next
+        end
+        response = build_response(raw_response, metadata, operation)
+        raise_api_error(response) unless response.success?
+
+        log(:debug, "Fly.io API #{verb.to_s.upcase} #{expanded_path} -> #{response.status}", metadata)
+        return response
+      end
+    end
+
+    def build_path(template, path_params = {})
+      value = String(template)
+      raise FlyIO::ArgumentError, "path must start with /" unless value.start_with?("/")
+      if value.match?(%r{\A//|[?#\\\x00]})
+        raise FlyIO::ArgumentError,
+              "path must not contain a URL, query, fragment, backslash, or NUL"
+      end
+
+      provided = stringify_keys(path_params)
+      result = value.gsub(/\{([^}]+)\}/) do
+        name = Regexp.last_match(1)
+        raise FlyIO::ArgumentError, "missing required path parameter: #{name}" unless provided.key?(name)
+
+        escape_path_component(provided.fetch(name), name)
+      end
+      unused = provided.keys - value.scan(/\{([^}]+)\}/).flatten
+      raise FlyIO::ArgumentError, "unknown path parameters: #{unused.join(', ')}" unless unused.empty?
+      if result.split("/").any? { |segment| [".", ".."].include?(URI.decode_www_form_component(segment)) }
+        raise FlyIO::ArgumentError, "path traversal segments are not allowed"
+      end
+
+      result
+    rescue URI::InvalidURIError, ::ArgumentError
+      raise FlyIO::ArgumentError, "path contains invalid encoding"
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(url: configuration.base_url, proxy: configuration.proxy) do |faraday|
+        faraday.options.open_timeout = configuration.open_timeout
+        faraday.options.timeout = configuration.request_timeout || configuration.read_timeout
+        faraday.options.read_timeout = configuration.read_timeout if faraday.options.respond_to?(:read_timeout=)
+        faraday.options.write_timeout = configuration.write_timeout if faraday.options.respond_to?(:write_timeout=)
+        faraday.adapter(configuration.adapter || Faraday.default_adapter)
+      end
+    end
+
+    def validate_method(method)
+      value = method.to_s.downcase.to_sym
+      raise FlyIO::ArgumentError, "unsupported HTTP method: #{method}" unless METHODS.include?(value)
+
+      value
+    end
+
+    def escape_path_component(value, name)
+      string = String(value)
+      raise FlyIO::ArgumentError, "path parameter #{name} must not be empty" if string.empty?
+      raise FlyIO::ArgumentError, "path parameter #{name} contains NUL" if string.include?("\0")
+
+      URI.encode_www_form_component(string).gsub("+", "%20")
+    end
+
+    def build_url(path, query)
+      pairs = query_pairs(query)
+      pairs.empty? ? path : "#{path}?#{URI.encode_www_form(pairs)}"
+    end
+
+    def absolute_url(relative_url)
+      base = URI.parse(configuration.base_url)
+      relative = URI.parse(relative_url)
+      base_path = base.path.to_s.sub(%r{/+\z}, "")
+      base.path = "#{base_path}/#{relative.path.delete_prefix('/')}"
+      base.query = relative.query
+      base.to_s
+    end
+
+    def query_pairs(query)
+      raise FlyIO::ArgumentError, "query must be a Hash" unless query.is_a?(Hash)
+
+      query.each_with_object([]) do |(key, value), pairs|
+        next if value.nil?
+
+        values = value.is_a?(Array) ? value : [value]
+        values.each { |item| pairs << [key.to_s, query_value(item)] unless item.nil? }
+      end
+    end
+
+    def query_value(value)
+      case value
+      when true then "true"
+      when false then "false"
+      else String(value)
+      end
+    end
+
+    def default_headers(accept)
+      {
+        "Accept" => accept,
+        "Authorization" => configuration.authorization_value,
+        "User-Agent" => configuration.user_agent
+      }
+    end
+
+    def encode_body(body, content_type, headers)
+      return nil if body.equal?(FlyIO::UNSET)
+
+      headers["Content-Type"] ||= content_type
+      serializable = serialize(body)
+      content_type.to_s.downcase.include?("json") ? JSON.generate(serializable) : serializable
+    end
+
+    def serialize(value)
+      case value
+      when Model then value.to_h
+      when Array then value.map { |item| serialize(item) }
+      when Hash then value.transform_keys(&:to_s).transform_values { |item| serialize(item) }
+      else value
+      end
+    end
+
+    def perform(method, url, headers, body, timeout)
+      if configuration.adapter.respond_to?(:call)
+        return configuration.adapter.call(method: method, url: url,
+                                          headers: headers, body: body, timeout: timeout)
+      end
+
+      @connection.run_request(method, url, body, headers) do |request|
+        request.options.timeout = timeout if timeout
+      end
+    end
+
+    def build_response(raw_response, request, operation)
+      status = Integer(raw_response.status)
+      headers = stringify_keys(raw_response.headers).transform_keys(&:downcase)
+      raw_body = raw_response.body
+      content_type = headers.fetch("content-type", "").downcase
+      parsed = parse_body(raw_body, content_type, status)
+      schema = operation&.response_schema(status, content_type)
+      body = schema ? SchemaRegistry.coerce(schema, parsed) : parsed
+      Response.new(status: status, headers: headers, body: body, raw_body: raw_body, request: request)
+    end
+
+    def parse_body(body, content_type, status)
+      return nil if status == 204 || body.nil? || body == ""
+      return body unless content_type.include?("json")
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def raise_api_error(response)
+      klass = ERROR_CLASSES[response.status] || (response.status >= 500 ? ServerError : APIError)
+      details = Redactor.redact_object(response.body)
+      message = error_message(response.status, details, response.request_id)
+      raise klass.new(message, status: response.status, headers: safe_headers(response.headers), details: details,
+                               request_id: response.request_id, request: response.request)
+    end
+
+    def error_message(status, details, request_id)
+      server_message = details.is_a?(Hash) && (details["error"] || details["message"])
+      ["Fly.io API request failed (HTTP #{status})", server_message,
+       ("request_id=#{request_id}" if request_id)].compact.join(": ")
+    end
+
+    def retry_status?(status, method, retry_unsafe)
+      RETRYABLE_STATUSES.include?(Integer(status)) && retry_allowed?(method, retry_unsafe)
+    end
+
+    def retry_allowed?(method, retry_unsafe)
+      SAFE_METHODS.include?(method) || retry_unsafe == true || (retry_unsafe.nil? && configuration.retry_unsafe)
+    end
+
+    def retry_delay(attempt, headers)
+      retry_after = stringify_keys(headers).find { |key, _| key.downcase == "retry-after" }&.last
+      parsed = parse_retry_after(retry_after)
+      return [parsed, configuration.max_retry_interval].min if parsed
+
+      base = [configuration.base_retry_interval * (2**attempt), configuration.max_retry_interval].min
+      [base + (base * configuration.retry_jitter * configuration.random.rand), configuration.max_retry_interval].min
+    end
+
+    def parse_retry_after(value)
+      return if value.nil?
+      return [Float(value), 0].max if value.to_s.match?(/\A\d+(?:\.\d+)?\z/)
+
+      [Time.httpdate(value.to_s) - Time.now, 0].max
+    rescue ::ArgumentError
+      nil
+    end
+
+    def safe_request_metadata(method, path, query, headers, body, operation)
+      {
+        method: method,
+        path: path,
+        query: Redactor.redact_object(query),
+        headers: safe_headers(headers),
+        body: Redactor.redact_object(body.equal?(FlyIO::UNSET) ? nil : serialize(body)),
+        operation_id: operation&.operation_id
+      }.freeze
+    end
+
+    def safe_headers(headers)
+      Redactor.redact_object(stringify_keys(headers))
+    end
+
+    def stringify_keys(hash)
+      hash.to_h.transform_keys(&:to_s)
+    end
+
+    def log(level, message, metadata)
+      configuration.logger&.public_send(level, "#{message} #{metadata.inspect}")
+    end
+  end
+end

data/lib/fly_io/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FlyIO
+  VERSION = "0.1.0"
+end

data/lib/fly_io.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "fly_io/version"
+require_relative "fly_io/errors"
+require_relative "fly_io/redactor"
+require_relative "fly_io/configuration"
+require_relative "fly_io/model"
+require_relative "fly_io/schema_registry"
+require_relative "fly_io/schema_validator"
+require_relative "fly_io/response"
+require_relative "fly_io/operation_registry"
+require_relative "fly_io/transport"
+require_relative "fly_io/resources/base"
+require_relative "fly_io/resources"
+require_relative "fly_io/client"
+require_relative "fly_io/graphql_client"
+
+module FlyIO
+  UNSET = Object.new.freeze
+
+  SchemaRegistry.install_model_constants!
+  Resources.install!
+end

data/script/check_api_coverage

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+ROOT = File.expand_path("..", __dir__)
+abort unless system(RbConfig.ruby, File.join(ROOT, "script/generate_api"), "--check")
+
+additional = JSON.parse(File.read(File.join(ROOT, "lib/fly_io/generated/additional_operations.json")))
+abort "Network Policies coverage drift" unless additional.fetch("operations").length == 3
+puts "Network Policies REST coverage OK: 3 documentation-derived operations (response contracts undocumented upstream)"
+network_source_hash = Digest::SHA256.file(File.join(ROOT, "contracts/sources/network-policies.html.markerb")).hexdigest
+abort "Network Policies source drift" unless network_source_hash == additional.fetch("generated_from").fetch("source_sha256")
+
+prometheus = JSON.parse(File.read(File.join(ROOT, "lib/fly_io/generated/prometheus_operations.json")))
+abort "Prometheus endpoint-family coverage drift" unless prometheus.fetch("operations").length == 7
+puts "Prometheus API coverage OK: 7 documented endpoint families (standard contract delegated upstream)"
+metrics_source_hash = Digest::SHA256.file(File.join(ROOT, "contracts/sources/metrics.html.md")).hexdigest
+abort "Prometheus source drift" unless metrics_source_hash == prometheus.fetch("generated_from").fetch("source_sha256")
+
+graphql_path = File.join(ROOT, "lib/fly_io/generated/graphql_operations.json")
+graphql = JSON.parse(File.read(graphql_path))
+operations = graphql.fetch("operations")
+names = operations.map { |operation| operation.fetch("name") }
+abort "duplicate GraphQL operation names" unless names.uniq.length == names.length
+operations.each do |operation|
+  abort "GraphQL operation #{operation['name']} lacks a document" if operation.fetch("document").strip.empty?
+  abort "GraphQL operation #{operation['name']} is not experimental" unless operation.fetch("stability") == "experimental"
+end
+counts = graphql.fetch("counts")
+abort "GraphQL inventory count drift" unless counts == {
+  "flyctl_named" => 27, "flyctl_ad_hoc" => 2, "fly_go" => 85, "official_examples" => 3, "total" => 117
+}
+schema_path = File.join(ROOT, "contracts/graphql/schema.graphql")
+schema_hash = Digest::SHA256.file(schema_path).hexdigest
+abort "GraphQL evidence schema drift" unless schema_hash == graphql.fetch("schema").fetch("sha256")
+schema_document = File.read(schema_path)
+root_fields = {"query" => "Queries", "mutation" => "Mutations"}.to_h do |kind, type_name|
+  block = schema_document.match(/^type #{type_name} \{$(.*?)^\}/m)&.captures&.first
+  abort "GraphQL evidence schema lacks #{type_name}" unless block
+  [kind, block.scan(/^  ([A-Za-z_]\w*)\s*(?:\(|:)/).flatten]
+end
+abort "GraphQL Query root count drift" unless root_fields.fetch("query").length == 39
+abort "GraphQL Mutation root count drift" unless root_fields.fetch("mutation").length == 141
+operations.each do |operation|
+  missing = operation.fetch("root_fields") - root_fields.fetch(operation.fetch("operation_type"))
+  abort "GraphQL operation #{operation['name']} has unknown roots: #{missing.join(', ')}" unless missing.empty?
+end
+graphql_source = JSON.parse(File.read(File.join(ROOT, "contracts/graphql/source.json")))
+{
+  "flyctl_operations.json" => graphql_source.dig("flyctl", "inventory_sha256"),
+  "fly_go_operations.json" => graphql_source.dig("fly_go", "inventory_sha256"),
+  "official_examples.json" => graphql_source.dig("official_examples", "inventory_sha256"),
+  "flyctl_named_operations.graphql" => graphql_source.dig("flyctl", "named_documents_sha256")
+}.each do |name, expected|
+  actual = Digest::SHA256.file(File.join(ROOT, "contracts/graphql", name)).hexdigest
+  abort "GraphQL source drift: #{name}" unless actual == expected
+end
+puts "GraphQL audit OK: 29 flyctl + 85 fly-go + 3 official experimental operations; raw documents supported"

data/script/fetch_openapi

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "digest"
+require "net/http"
+require "uri"
+
+url = URI("https://docs.machines.dev/openapi.json")
+response = Net::HTTP.get_response(url)
+abort "OpenAPI fetch failed: HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+snapshot = File.binread(File.expand_path("../contracts/machines/openapi.json", __dir__))
+expected = Digest::SHA256.hexdigest(snapshot)
+actual = Digest::SHA256.hexdigest(response.body)
+abort "upstream OpenAPI drift: committed=#{expected} upstream=#{actual}" unless expected == actual
+
+puts "OpenAPI upstream matches committed snapshot: sha256=#{actual} " \
+     "etag=#{response['etag'].inspect} last-modified=#{response['last-modified'].inspect}"