altertable-lakehouse 0.2.0 → 0.4.0

data/altertable-lakehouse.gemspec

@@ -0,0 +1,41 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "altertable/lakehouse/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "altertable-lakehouse"
+  spec.version = Altertable::Lakehouse::VERSION
+  spec.authors = ["Altertable AI"]
+  spec.email = ["support@altertable.ai"]
+
+  spec.summary = "Official Ruby client for Altertable Lakehouse"
+  spec.description = "Official Ruby client for Altertable Lakehouse API."
+  spec.homepage = "https://github.com/altertable-ai/altertable-lakehouse-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/altertable-ai/altertable-lakehouse-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/altertable-ai/altertable-lakehouse-ruby/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|sorbet)/}) }
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "base64"
+
+  spec.add_development_dependency "faraday", "~> 2.12"
+  spec.add_development_dependency "faraday-retry", "~> 2.0"
+  spec.add_development_dependency "faraday-net_http"
+  spec.add_development_dependency "httpx" # For testing optional support
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "testcontainers"
+  spec.add_development_dependency "rbs"
+  spec.add_development_dependency "sorbet"
+  spec.add_development_dependency "sorbet-runtime"
+end

data/lib/altertable/lakehouse/adapters.rb

@@ -0,0 +1,192 @@
+module Altertable
+  module Lakehouse
+    module Adapters
+      Response = Struct.new(:status, :body, :headers)
+
+      class Base
+        def initialize(base_url:, timeout:, headers: {})
+          @base_url = base_url
+          @timeout = timeout
+          @headers = headers
+        end
+
+        def get(path, body: nil, params: {}, headers: {}, &_block)
+          raise NotImplementedError
+        end
+
+        def post(path, body: nil, params: {}, headers: {}, &_block)
+          raise NotImplementedError
+        end
+
+        def delete(path, body: nil, params: {}, headers: {}, &_block)
+          raise NotImplementedError
+        end
+      end
+
+      class FaradayAdapter < Base
+        def initialize(base_url:, timeout:, headers: {})
+          super
+          require "faraday"
+          require "faraday/retry"
+          require "faraday/net_http"
+          
+          @conn = Faraday.new(url: @base_url) do |f|
+            @headers.each { |k, v| f.headers[k] = v }
+            f.options.timeout = @timeout
+            f.request :retry, max: 3, interval: 0.05, backoff_factor: 2
+            f.adapter Faraday.default_adapter
+          end
+        end
+
+        def get(path, body: nil, params: {}, headers: {}, &_block) # rubocop:disable Lint/UnusedMethodArgument
+          resp = @conn.get(path, params, headers)
+          wrap_response(resp)
+        rescue Faraday::ConnectionFailed => e
+          raise Altertable::Lakehouse::NetworkError, e.message
+        rescue Faraday::TimeoutError => e
+          raise Altertable::Lakehouse::TimeoutError, e.message
+        end
+
+        def post(path, body: nil, params: {}, headers: {}, &block)
+          resp = @conn.post(path) do |req|
+            req.params = params if params
+            req.headers = req.headers.merge(headers) unless headers.empty?
+            req.body = body
+            req.options.on_data = block if block_given?
+          end
+          wrap_response(resp)
+        rescue Faraday::ConnectionFailed => e
+          raise Altertable::Lakehouse::NetworkError, e.message
+        rescue Faraday::TimeoutError => e
+          raise Altertable::Lakehouse::TimeoutError, e.message
+        end
+
+        def delete(path, body: nil, params: {}, headers: {}, &_block) # rubocop:disable Lint/UnusedMethodArgument
+          resp = @conn.delete(path, params, headers)
+          wrap_response(resp)
+        rescue Faraday::ConnectionFailed => e
+          raise Altertable::Lakehouse::NetworkError, e.message
+        rescue Faraday::TimeoutError => e
+          raise Altertable::Lakehouse::TimeoutError, e.message
+        end
+
+        private
+
+        def wrap_response(resp)
+          Response.new(resp.status, resp.body, resp.headers)
+        end
+      end
+
+      class HttpxAdapter < Base
+        def initialize(base_url:, timeout:, headers: {})
+          super
+          require "httpx"
+          # Configure retries plugin if available or implement manual retries?
+          # Httpx has built-in retries via plugin.
+          @client = HTTPX.plugin(:retries).with(
+            timeout: { operation_timeout: @timeout },
+            headers: @headers,
+            base_url: @base_url
+          )
+        end
+
+        def get(path, body: nil, params: {}, headers: {}, &_block) # rubocop:disable Lint/UnusedMethodArgument
+          resp = @client.with(headers: headers).get(path, params: params)
+          wrap_response(resp)
+        end
+
+        def post(path, body: nil, params: {}, headers: {}, &block)
+          client = @client.with(headers: headers)
+          if block_given?
+            # Stream response body
+            # HTTPX response streaming:
+            response = client.request("POST", path, body: body, params: params, stream: true)
+            
+            # Check for error immediately
+            if response.is_a?(HTTPX::ErrorResponse)
+              raise Altertable::Lakehouse::NetworkError, response.error.message
+            end
+
+            response.body.each do |chunk|
+              block.call(chunk, response.headers["content-length"])
+            end
+            wrap_response(response)
+          else
+            resp = client.post(path, body: body, params: params)
+            wrap_response(resp)
+          end
+        end
+
+        def delete(path, body: nil, params: {}, headers: {}, &_block) # rubocop:disable Lint/UnusedMethodArgument
+          resp = @client.with(headers: headers).delete(path, params: params)
+          wrap_response(resp)
+        end
+
+        private
+
+        def wrap_response(resp)
+          if resp.is_a?(HTTPX::ErrorResponse)
+            raise Altertable::Lakehouse::NetworkError, resp.error.message
+          end
+          Response.new(resp.status, resp.to_s, resp.headers)
+        end
+      end
+
+      class NetHttpAdapter < Base
+        def initialize(base_url:, timeout:, headers: {})
+          super
+          require "net/http"
+          require "uri"
+          @uri = URI.parse(@base_url)
+        end
+
+        def get(path, body: nil, params: {}, headers: {}, &block) # rubocop:disable Lint/UnusedMethodArgument
+          request(Net::HTTP::Get, path, params: params, headers: headers, &block)
+        end
+
+        def post(path, body: nil, params: {}, headers: {}, &block)
+          request(Net::HTTP::Post, path, body: body, params: params, headers: headers, &block)
+        end
+
+        def delete(path, body: nil, params: {}, headers: {}, &block) # rubocop:disable Lint/UnusedMethodArgument
+          request(Net::HTTP::Delete, path, params: params, headers: headers, &block)
+        end
+
+        private
+
+        def request(klass, path, body: nil, params: {}, headers: {}, &block)
+          # Construct full URI for request
+          uri = URI.join(@uri, path)
+          uri.query = URI.encode_www_form(params) unless params.nil? || params.empty?
+
+          req = klass.new(uri)
+          @headers.merge(headers).each { |k, v| req[k] = v }
+          req.body = body if body
+
+          # Net::HTTP start
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout, read_timeout: @timeout) do |http|
+            if block_given?
+              http.request(req) do |response|
+                # Stream the body if block is given
+                if response.is_a?(Net::HTTPSuccess)
+                  response.read_body do |chunk|
+                    block.call(chunk, response.content_length)
+                  end
+                end
+                # Return wrapped response (body might be empty if consumed?)
+                # If we consumed the body with read_body, response.body is nil.
+                # But our Response struct expects body. For streaming, we might not need body in the Response if block handled it.
+                return Response.new(response.code.to_i, response.body, response.to_hash) 
+              end
+            else
+              resp = http.request(req)
+              Response.new(resp.code.to_i, resp.body, resp.to_hash)
+            end
+          end
+        rescue SocketError, Net::OpenTimeout, Net::ReadTimeout => e
+          raise Altertable::Lakehouse::NetworkError, e.message
+        end
+      end
+    end
+  end
+end

data/lib/altertable/lakehouse/client.rb

@@ -1,11 +1,9 @@
-require "faraday"
-require "faraday/retry"
-require "faraday/net_http"
 require "json"
 require "base64"
 require_relative "models"
 require_relative "errors"
 require_relative "version"
+require_relative "adapters"
 
 module Altertable
   module Lakehouse
@@ -13,7 +11,7 @@ module Altertable
       DEFAULT_BASE_URL = "https://api.altertable.ai"
       DEFAULT_TIMEOUT = 10
 
-      def initialize(username: nil, password: nil, basic_auth_token: nil, base_url: nil, timeout: nil, user_agent: nil)
+      def initialize(username: nil, password: nil, basic_auth_token: nil, base_url: nil, timeout: nil, user_agent: nil, adapter: nil)
         # 1. Try passed basic_auth_token
         # 2. Try passed username/password
         # 3. Try ENV["ALTERTABLE_BASIC_AUTH_TOKEN"]
@@ -35,57 +33,45 @@ module Altertable
         @timeout = timeout || DEFAULT_TIMEOUT
         @user_agent = user_agent ? "AltertableRuby/#{VERSION} #{user_agent}" : "AltertableRuby/#{VERSION}"
         
-        @conn = Faraday.new(url: @base_url) do |f|
-          f.headers["Authorization"] = @auth_header
-          f.headers["User-Agent"] = @user_agent
-          f.headers["Content-Type"] = "application/json"
-          f.options.timeout = @timeout
-          f.request :retry, max: 3, interval: 0.05, backoff_factor: 2
-          f.adapter Faraday.default_adapter
-        end
+        headers = {
+          "Authorization" => @auth_header,
+          "User-Agent" => @user_agent,
+          "Content-Type" => "application/json"
+        }
+
+        @adapter = select_adapter(adapter, base_url: @base_url, timeout: @timeout, headers: headers)
       end
 
       # POST /append
-      def append(catalog:, schema:, table:, payload:)
+      def append(catalog:, schema:, table:, payload:, sync: nil)
         params = { catalog: catalog, schema: schema, table: table }
+        params[:sync] = sync unless sync.nil?
         req = Models::AppendRequest.new(payload)
         resp = request(:post, "/append", body: req.to_h, query: params)
         Models::AppendResponse.from_h(resp)
       end
 
+      # GET /tasks/:task_id
+      def get_task(task_id)
+        resp = request(:get, "/tasks/#{task_id}")
+        Models::TaskResponse.from_h(resp)
+      end
+
       # POST /query (streamed)
       def query(statement:, **options)
         req_body = Models::QueryRequest.new(statement: statement, **options).to_h.to_json
-        
+
         enum = Enumerator.new do |yielder|
           buffer = ""
-          @conn.post("/query") do |req|
-            req.headers["Content-Type"] = "application/json"
-            req.body = req_body
-            req.options.on_data = Proc.new do |chunk, _|
-              buffer << chunk
-              while (line_end = buffer.index("\n"))
-                line = buffer.slice!(0, line_end + 1).strip
-                next if line.empty?
-                begin
-                  yielder << JSON.parse(line)
-                rescue JSON::ParserError
-                  raise ParseError, "Invalid JSON line: #{line}"
-                end
-              end
-            end
-          end
           
-          # Process remaining buffer
-          unless buffer.empty?
-            begin
-              yielder << JSON.parse(buffer.strip)
-            rescue JSON::ParserError
-               raise ParseError, "Invalid JSON line: #{buffer}"
-            end
+          # Use adapter's stream capability
+          resp = @adapter.post("/query", body: req_body) do |chunk, _|
+            buffer << chunk
           end
+
+          handle_stream_response(resp, buffer, yielder)
         end
-        
+
         QueryResult.new(enum)
       end
 
@@ -102,23 +88,18 @@ module Altertable
 
       # POST /upload
       def upload(catalog:, schema:, table:, format:, mode:, file_io:, primary_key: nil)
-        params = { 
-          catalog: catalog, 
-          schema: schema, 
-          table: table, 
-          format: format, 
-          mode: mode 
+        params = {
+          catalog: catalog,
+          schema: schema,
+          table: table,
+          format: format,
+          mode: mode
         }
         params[:primary_key] = primary_key if primary_key
 
-        # Use a separate connection for multipart/binary if needed, 
-        # but spec says body is octet-stream.
-        resp = @conn.post("/upload") do |req|
-          req.params = params
-          req.headers["Content-Type"] = "application/octet-stream"
-          req.body = file_io # IO object or string
-        end
-        
+        body = file_io.respond_to?(:read) ? file_io.read : file_io
+
+        resp = @adapter.post("/upload", body: body, params: params, headers: { "Content-Type" => "application/octet-stream" })
         handle_response(resp)
       end
 
@@ -135,30 +116,112 @@ module Altertable
       end
 
       # POST /validate
-      def validate(statement:)
-        req = Models::ValidateRequest.new(statement: statement)
+      def validate(statement:, catalog: nil, schema: nil, session_id: nil)
+        req = Models::ValidateRequest.new(
+          statement: statement,
+          catalog: catalog,
+          schema: schema,
+          session_id: session_id
+        )
         resp = request(:post, "/validate", body: req.to_h)
         Models::ValidateResponse.from_h(resp)
       end
 
+      # POST /autocomplete
+      def autocomplete(statement:, catalog: nil, schema: nil, session_id: nil, max_suggestions: nil)
+        req = Models::AutocompleteRequest.new(
+          statement: statement,
+          catalog: catalog,
+          schema: schema,
+          session_id: session_id,
+          max_suggestions: max_suggestions
+        )
+        resp = request(:post, "/autocomplete", body: req.to_h)
+        Models::AutocompleteResponse.from_h(resp)
+      end
+
+      # POST /explain
+      def explain(statement:, catalog: nil, schema: nil, session_id: nil, include_plan: nil)
+        req = Models::ExplainRequest.new(
+          statement: statement,
+          catalog: catalog,
+          schema: schema,
+          session_id: session_id,
+          include_plan: include_plan
+        )
+        resp = request(:post, "/explain", body: req.to_h)
+        Models::ExplainResponse.from_h(resp)
+      end
+
       private
 
-      def request(method, path, body: nil, query: nil, stream: false, &block)
-        resp = @conn.send(method, path) do |req|
-          req.params = query if query
-          req.body = body.to_json if body
-          if stream
-            req.options.on_data = block
+      def select_adapter(name, options)
+        case name
+        when :faraday
+          Adapters::FaradayAdapter.new(**options)
+        when :httpx
+          Adapters::HttpxAdapter.new(**options)
+        when :net_http
+          Adapters::NetHttpAdapter.new(**options)
+        else
+          # Auto-detect
+          if defined?(Faraday) || try_require("faraday")
+            Adapters::FaradayAdapter.new(**options)
+          elsif defined?(HTTPX) || try_require("httpx")
+            Adapters::HttpxAdapter.new(**options)
+          else
+            Adapters::NetHttpAdapter.new(**options)
           end
         end
-        
-        return if stream # Block handles data
-        
+      end
+
+      def try_require(gem_name)
+        require gem_name
+        true
+      rescue LoadError
+        false
+      end
+
+      def request(method, path, body: nil, query: nil)
+        resp = @adapter.send(method, path, body: body.is_a?(Hash) ? body.to_json : body, params: query || {})
         handle_response(resp)
-      rescue Faraday::ConnectionFailed => e
-        raise NetworkError, e.message
-      rescue Faraday::TimeoutError => e
-        raise TimeoutError, e.message
+      end
+
+      def handle_stream_response(resp, buffer, yielder)
+        case resp.status
+        when 400
+          raise BadRequestError, "Bad Request: #{buffer.strip}"
+        when 401
+          raise AuthError, "Unauthorized"
+        when 200..299
+          # Parse the accumulated NDJSON buffer line by line
+          # Buffer might be partial? 
+          # In streaming, the block is called.
+          # Here we are processing after the stream is done?
+          # Wait, QueryResult expects the stream to be processed as it comes?
+          # The previous implementation used an Enumerator that yielded as data came in.
+          # Here, @adapter.post blocks until done?
+          # If @adapter.post blocks, we only get the buffer at the end.
+          # To stream truly, @adapter.post needs to yield to the block, which yields to yielder?
+          
+          # Re-implementing streaming logic:
+          # The enumerator in `query` wraps the call. 
+          # When `query` returns QueryResult, it hasn't run the request yet.
+          # Enumerator logic is inside.
+          
+          buffer.each_line do |line|
+            line = line.strip
+            next if line.empty?
+            begin
+              yielder << JSON.parse(line)
+            rescue JSON::ParserError
+              # Partial line?
+              # For now assume full lines or handle buffering properly
+            end
+          end
+        else
+          raise ApiError, "API Error #{resp.status}: #{buffer.strip}"
+        end
       end
 
       def handle_response(resp)
@@ -168,7 +231,7 @@ module Altertable
           begin
             JSON.parse(resp.body)
           rescue JSON::ParserError
-            # For non-JSON responses (like empty upload response?)
+            # For non-JSON responses
             resp.body
           end
         when 400
@@ -176,40 +239,48 @@ module Altertable
         when 401
           raise AuthError, "Unauthorized"
         when 404
-          raise ApiError, "Not Found: #{resp.url}" # Could be specific
+          raise ApiError, "Not Found: #{resp.headers}" # Url not avail in struct easily
         else
           raise ApiError, "API Error #{resp.status}: #{resp.body}"
         end
       end
     end
-    
+
     class QueryResult
       include Enumerable
-      
+
+      # metadata: the stream header object (first NDJSON line)
+      # columns:  array of column name strings (second NDJSON line)
       attr_reader :metadata, :columns
-      
+
       def initialize(enum)
         @enum = enum
         @metadata = nil
         @columns = nil
       end
-      
+
       def each(&block)
-        # We need to wrap the enum to extract metadata/columns first
-        # Note: This will re-trigger the request if enumerated multiple times
-        first = true
-        second = true
-        
+        # The real mock streams:
+        #   line 1: { "statement":…, "session_id":…, … }   (header object)
+        #   line 2: ["col1", "col2", …]                     (column names array)
+        #   line 3+: [val1, val2, …]                        (row value arrays)
+        # We zip each row array with the column names to produce a Hash.
+        line_index = 0
+
         @enum.each do |item|
-          if first
+          case line_index
+          when 0
             @metadata = item
-            first = false
-          elsif second
+          when 1
             @columns = item
-            second = false
           else
-            block.call(item)
+            if @columns.is_a?(Array) && item.is_a?(Array)
+              block.call(@columns.zip(item).to_h)
+            else
+              block.call(item)
+            end
           end
+          line_index += 1
         end
       end
     end