fly_io 0.1.0

data/lib/fly_io/graphql_client.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FlyIO
+  # Fly documents this control-plane GraphQL endpoint as internal and unstable.
+  # Raw documents are first class; generated flyctl-observed operations live
+  # behind #experimental and carry no compatibility guarantee.
+  class GraphQLClient
+    INTROSPECTION_PATTERN = /\b__(?:schema|type)\b/
+
+    attr_reader :configuration, :transport
+
+    def initialize(configuration = nil, **)
+      @configuration = configuration || Configuration.new(**)
+      graphql_configuration = @configuration.with(base_url: graphql_origin)
+      @transport = Transport.new(graphql_configuration)
+      freeze
+    end
+
+    def query(document:, variables: {}, operation_name: nil, headers: {}, timeout: nil,
+              retry_unsafe: false, introspection: false)
+      validate_document!(document, introspection)
+      body = {"query" => String(document), "variables" => variables}
+      body["operationName"] = operation_name if operation_name
+      response = transport.request(method: :post, path: graphql_path, headers: headers, body: body,
+                                   retry_unsafe: retry_unsafe, timeout: timeout)
+      errors = response.body.is_a?(Hash) ? response.body["errors"] : nil
+      if errors&.any?
+        raise GraphQLError.new(graphql_errors: errors, status: response.status, headers: response.headers,
+                               request_id: response.request_id, request: response.request)
+      end
+
+      response
+    end
+
+    alias execute query
+
+    def introspect(document:, **)
+      query(document: document, introspection: true, **)
+    end
+
+    def experimental
+      ExperimentalGraphQL.new(self)
+    end
+
+    private
+
+    def validate_document!(document, introspection)
+      value = String(document)
+      raise FlyIO::ArgumentError, "GraphQL document must not be empty" if value.strip.empty?
+      return unless value.match?(INTROSPECTION_PATTERN)
+      return if introspection && configuration.introspection
+
+      raise FlyIO::ArgumentError,
+            "GraphQL introspection requires Configuration(introspection: true) and introspection: true"
+    end
+
+    def graphql_path
+      require "uri"
+      uri = URI(configuration.graphql_url)
+      if uri.query
+        "#{uri.path}?#{uri.query}"
+      else
+        (uri.path.empty? ? "/" : uri.path)
+      end
+    end
+
+    def graphql_origin
+      uri = URI(configuration.graphql_url)
+      uri.path = ""
+      uri.query = nil
+      uri.to_s
+    end
+  end
+
+  class ExperimentalGraphQL
+    MANIFEST_PATH = File.expand_path("generated/graphql_operations.json", __dir__)
+
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+      freeze
+    end
+
+    def operations
+      self.class.operations
+    end
+
+    def execute(name, variables: {}, **)
+      operation = operations.find { |entry| entry.fetch("name") == name.to_s }
+      raise FlyIO::ArgumentError, "unknown experimental GraphQL operation: #{name}" unless operation
+
+      client.query(document: operation.fetch("document"), operation_name: operation["operation_name"],
+                   variables: variables, **)
+    end
+
+    def self.operations
+      @operations ||= JSON.parse(File.read(MANIFEST_PATH)).fetch("operations").freeze
+    end
+  end
+end

data/lib/fly_io/model.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module FlyIO
+  module Models; end
+
+  class Model
+    attr_reader :attributes, :schema_name
+
+    def initialize(attributes = nil, schema_name: if self.class.const_defined?(:SCHEMA_NAME,
+                                                                               false)
+                                                    self.class::SCHEMA_NAME
+                                                  end,
+                   **keyword_attributes)
+      if attributes && !keyword_attributes.empty?
+        raise FlyIO::ArgumentError, "provide model attributes as a Hash or keywords, not both"
+      end
+
+      attributes ||= keyword_attributes
+      raise FlyIO::ArgumentError, "model attributes must be a Hash" unless attributes.is_a?(Hash)
+
+      @schema_name = schema_name
+      @attributes = attributes.each_with_object({}) do |(key, value), result|
+        result[key.to_s] = SchemaRegistry.coerce_property(schema_name, key.to_s, value)
+      end.freeze
+      freeze
+    end
+
+    def [](key)
+      attributes[key.to_s]
+    end
+
+    def key?(key)
+      attributes.key?(key.to_s)
+    end
+
+    def to_h
+      attributes.transform_values { |value| serialize(value) }
+    end
+
+    def method_missing(name, *arguments)
+      return self[name] if arguments.empty? && key?(name)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      key?(name) || super
+    end
+
+    def ==(other)
+      other.is_a?(Model) && other.schema_name == schema_name && other.attributes == attributes
+    end
+
+    private
+
+    def serialize(value)
+      case value
+      when Model then value.to_h
+      when Array then value.map { |item| serialize(item) }
+      when Hash then value.transform_values { |item| serialize(item) }
+      else value
+      end
+    end
+  end
+end

data/lib/fly_io/operation_registry.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FlyIO
+  module OperationRegistry
+    MANIFEST_PATHS = %w[operations.json additional_operations.json prometheus_operations.json].map do |name|
+      File.expand_path("generated/#{name}", __dir__)
+    end.freeze
+
+    module_function
+
+    def operations
+      @operations ||= MANIFEST_PATHS.flat_map do |path|
+        JSON.parse(File.read(path)).fetch("operations")
+      end.map { |data| Operation.new(data) }.freeze
+    end
+
+    def resources
+      @resources ||= operations.group_by(&:ruby_resource).transform_values(&:freeze).freeze
+    end
+
+    def fetch(identity_or_operation_id, method: nil, path: nil)
+      key = identity_or_operation_id.to_s
+      matches = operations.select do |operation|
+        (operation.identity == key || operation.operation_id == key) &&
+          (!method || operation.http_method == method.to_s.downcase) &&
+          (!path || operation.path == path)
+      end
+      raise FlyIO::ArgumentError, "unknown operation: #{key}" if matches.empty?
+      if matches.length > 1
+        raise FlyIO::ArgumentError, "ambiguous operation ID #{key}; specify method: and path:"
+      end
+
+      matches.first
+    end
+
+    class Operation
+      attr_reader :data
+
+      def initialize(data)
+        @data = data.freeze
+        freeze
+      end
+
+      %w[identity surface stability base_url operation_id path ruby_resource ruby_method summary].each do |name|
+        define_method(name) { data[name] }
+      end
+
+      def http_method
+        data.fetch("method")
+      end
+
+      def parameters
+        data.fetch("parameters")
+      end
+
+      def request_body
+        data["request_body"]
+      end
+
+      def responses
+        data.fetch("responses")
+      end
+
+      def response_schema(status, content_type)
+        response = responses[status.to_s] || responses["default"]
+        return unless response
+
+        content = response.fetch("content", {})
+        return if content.empty?
+
+        normalized_type = content_type.to_s.split(";", 2).first.to_s.downcase
+        exact = content[normalized_type]
+        exact&.fetch("schema", nil) || content.values.first&.fetch("schema", nil)
+      end
+    end
+  end
+end

data/lib/fly_io/redactor.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module FlyIO
+  module Redactor
+    FILTERED = "[FILTERED]"
+    SENSITIVE_KEYS = /authorization|token|secret|password|credential|private.?key|certificate/i
+    AUTHORIZATION_VALUE = %r{\b(?:Bearer|FlyV1)\s+[A-Za-z0-9._~+/=:-]+}i
+
+    module_function
+
+    def redact(value)
+      value.to_s.gsub(AUTHORIZATION_VALUE) { |match| "#{match.split.first} #{FILTERED}" }
+    end
+
+    def redact_object(value, key = nil)
+      return FILTERED if key&.match?(SENSITIVE_KEYS)
+
+      case value
+      when Model
+        redact_object(value.to_h, key)
+      when Hash
+        value.each_with_object({}) do |(child_key, child), result|
+          result[child_key] = redact_object(child, child_key.to_s)
+        end
+      when Array
+        value.map { |child| redact_object(child) }
+      when String
+        redact(value)
+      else
+        value
+      end
+    end
+  end
+end

data/lib/fly_io/resources/base.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module FlyIO
+  module Resources
+    class Base
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+        freeze
+      end
+
+      def operation(operation_id, method: nil, path: nil, **arguments)
+        invoke(OperationRegistry.fetch(operation_id, method: method, path: path), arguments)
+      end
+
+      private
+
+      def invoke(operation, arguments)
+        arguments = arguments.dup
+        body = arguments.delete(:body) { FlyIO::UNSET }
+        extra_headers = arguments.delete(:headers) || {}
+        retry_unsafe = arguments.delete(:retry_unsafe)
+        request_timeout = arguments.delete(:request_timeout)
+        path_params = {}
+        query = {}
+        operation_headers = {}
+
+        operation.parameters.each do |parameter|
+          ruby_name = parameter.fetch("ruby_name").to_sym
+          present = arguments.key?(ruby_name)
+          value = arguments.delete(ruby_name)
+          if parameter["required"] && (!present || value.nil?)
+            raise FlyIO::ArgumentError, "#{operation.ruby_method}: #{ruby_name} is required"
+          end
+          next unless present
+
+          SchemaValidator.validate!(parameter["schema"], value, location: ruby_name.to_s)
+          target = {"path" => path_params, "query" => query, "header" => operation_headers}.fetch(parameter.fetch("in"))
+          target[parameter.fetch("name")] = value
+        end
+
+        unless arguments.empty?
+          raise FlyIO::ArgumentError, "#{operation.ruby_method}: unknown keywords: #{arguments.keys.join(', ')}"
+        end
+        if operation.request_body&.fetch("required", false) && body.equal?(FlyIO::UNSET)
+          raise FlyIO::ArgumentError, "#{operation.ruby_method}: body is required"
+        end
+
+        unless body.equal?(FlyIO::UNSET)
+          SchemaValidator.validate!(operation.request_body&.dig("schema"), body, location: "body")
+        end
+
+        client.transport_for(operation).request(
+          method: operation.http_method,
+          path: operation.path,
+          path_params: path_params,
+          query: query,
+          headers: operation_headers.merge(extra_headers),
+          body: body,
+          retry_unsafe: retry_unsafe,
+          timeout: request_timeout,
+          operation: operation
+        )
+      end
+    end
+  end
+end

data/lib/fly_io/resources.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module FlyIO
+  module Resources
+    module_function
+
+    def install!
+      OperationRegistry.resources.each do |resource_name, operations|
+        constant_name = resource_name.split("_").map(&:capitalize).join
+        klass = if const_defined?(constant_name, false)
+                  const_get(constant_name, false)
+                else
+                  const_set(constant_name, Class.new(Base))
+                end
+        operations.each do |operation|
+          next if klass.public_method_defined?(operation.ruby_method.to_sym, false)
+
+          klass.define_method(operation.ruby_method) do |**arguments|
+            invoke(operation, arguments)
+          end
+        end
+      end
+    end
+
+    def class_for(resource_name)
+      install!
+      const_get(resource_name.split("_").map(&:capitalize).join, false)
+    end
+  end
+end

data/lib/fly_io/response.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module FlyIO
+  class Response
+    attr_reader :status, :headers, :body, :raw_body, :request, :request_id
+
+    def initialize(status:, headers:, body:, raw_body:, request:)
+      @status = Integer(status)
+      @headers = headers.freeze
+      @body = body
+      @raw_body = raw_body
+      @request = request.freeze
+      @request_id = headers["fly-request-id"] || headers["x-request-id"]
+      freeze
+    end
+
+    alias data body
+
+    def success?
+      (200..299).cover?(status)
+    end
+
+    def accepted?
+      status == 202
+    end
+
+    def no_content?
+      status == 204
+    end
+
+    def [](key)
+      body.respond_to?(:[]) ? body[key] : nil
+    end
+
+    def method_missing(name, *arguments)
+      return body.public_send(name) if arguments.empty? && body.respond_to?(name)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      body.respond_to?(name, include_private) || super
+    end
+  end
+end

data/lib/fly_io/schema_registry.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FlyIO
+  module SchemaRegistry
+    module_function
+
+    def schemas
+      @schemas ||= JSON.parse(File.read(File.expand_path("generated/schemas.json", __dir__))).freeze
+    end
+
+    def install_model_constants!
+      schemas.each do |name, schema|
+        constant_name = schema.fetch("x-ruby-class")
+        next if Models.const_defined?(constant_name, false)
+
+        schema_name = name
+        klass = Class.new(Model)
+        klass.const_set(:SCHEMA_NAME, schema_name.freeze)
+        Models.const_set(constant_name, klass)
+      end
+    end
+
+    def build(name, attributes)
+      install_model_constants!
+      Models.const_get(schemas.fetch(name).fetch("x-ruby-class"), false).new(attributes)
+    end
+
+    def coerce(schema, value)
+      return value if value.nil? || !schema || !schema.is_a?(Hash)
+
+      schema = resolve(schema)
+      if (reference = schema["$resolved_ref"]) && value.is_a?(Hash)
+        return build(reference, value)
+      end
+
+      schema = flatten_all_of(schema)
+
+      case schema["type"]
+      when "array"
+        value.is_a?(Array) ? value.map { |item| coerce(schema["items"], item) } : value
+      when "object"
+        coerce_object(schema, value)
+      else
+        value
+      end
+    end
+
+    def coerce_property(schema_name, property, value)
+      schema = schemas[schema_name]
+      coerce(schema&.dig("properties", property), value)
+    end
+
+    def resolve(schema)
+      reference = schema["$ref"]
+      return schema unless reference
+
+      name = if reference.start_with?("#/components/schemas/")
+               reference.delete_prefix("#/components/schemas/")
+             elsif reference.start_with?("#/additional/schemas/")
+               reference.delete_prefix("#/additional/schemas/")
+             else
+               raise FlyIO::ArgumentError, "unsupported schema reference: #{reference}"
+             end
+      schemas.fetch(name).merge("$resolved_ref" => name)
+    end
+
+    def flatten_all_of(schema)
+      return schema unless schema["allOf"]
+
+      schema["allOf"].reduce(schema.except("allOf")) do |result, member|
+        resolved = flatten_all_of(resolve(member).except("$resolved_ref"))
+        result.merge(resolved) do |key, left, right|
+          key == "properties" ? left.merge(right) : right
+        end
+      end
+    end
+
+    def coerce_object(schema, value)
+      return value unless value.is_a?(Hash)
+
+      properties = schema.fetch("properties", {})
+      value.each_with_object({}) do |(key, child), result|
+        result[key.to_s] = coerce(properties[key.to_s] || schema["additionalProperties"], child)
+      end
+    end
+  end
+end

data/lib/fly_io/schema_validator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module FlyIO
+  module SchemaValidator
+    module_function
+
+    def validate!(schema, value, location: "value")
+      return if schema.nil? || !schema.is_a?(Hash)
+
+      schema = SchemaRegistry.flatten_all_of(SchemaRegistry.resolve(schema))
+      raw = value.is_a?(Model) ? value.to_h : value
+      validate_type!(schema["type"], raw, location)
+      validate_enum!(schema["enum"], raw, location)
+      validate_object!(schema, raw, location) if raw.is_a?(Hash)
+      validate_array!(schema, raw, location) if raw.is_a?(Array)
+      true
+    end
+
+    def validate_type!(type, value, location)
+      return if type.nil? || value.nil?
+
+      valid = case type
+              when "object" then value.is_a?(Hash)
+              when "array" then value.is_a?(Array)
+              when "string" then value.is_a?(String)
+              when "integer" then value.is_a?(Integer)
+              when "number" then value.is_a?(Numeric)
+              when "boolean" then [true, false].include?(value)
+              else true
+              end
+      raise FlyIO::ArgumentError, "#{location} must be #{type}" unless valid
+    end
+
+    def validate_enum!(enum, value, location)
+      return unless enum && !value.nil? && !enum.include?(value)
+
+      raise FlyIO::ArgumentError, "#{location} must be one of: #{enum.join(', ')}"
+    end
+
+    def validate_object!(schema, value, location)
+      normalized = value.transform_keys(&:to_s)
+      Array(schema["required"]).each do |name|
+        unless normalized.key?(name) && !normalized[name].nil?
+          raise FlyIO::ArgumentError, "#{location}.#{name} is required"
+        end
+      end
+      schema.fetch("properties", {}).each do |name, property_schema|
+        validate!(property_schema, normalized[name], location: "#{location}.#{name}") if normalized.key?(name)
+      end
+    end
+
+    def validate_array!(schema, value, location)
+      value.each_with_index { |item, index| validate!(schema["items"], item, location: "#{location}[#{index}]") }
+    end
+  end
+end