volcano-sdk 0.5.2

data/lib/volcano/connection_string.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+# Public namespace for Volcano SDK helpers.
+module Volcano
+  FULL_ACCESS_APP_NAME = 'volcano_full_access'
+  USER_ACCESS_APP_NAME = 'volcano_user_access'
+  CONNECTION_URI_PREFIX = %r{\Apostgres(?:ql)?://}
+  INVALID_PERCENT_ENCODING = /%(?![0-9A-Fa-f]{2})/
+  private_constant :FULL_ACCESS_APP_NAME, :USER_ACCESS_APP_NAME,
+                   :CONNECTION_URI_PREFIX, :INVALID_PERCENT_ENCODING
+
+  module_function
+
+  def database_connection_string(base_connection_string, user_id: nil)
+    unless base_connection_string.is_a?(String) && !base_connection_string.empty?
+      raise ArgumentError,
+            'database_connection_string: base_connection_string (DATABASE_URL) is required'
+    end
+
+    target, query = database_connection_parts(base_connection_string)
+    parameters = database_query_parameters(query)
+    parameters << "application_name=#{database_application_name_query_value(user_id)}"
+    "#{target}?#{parameters.join('&')}"
+  end
+
+  def database_connection_parts(value)
+    prefix_end = database_connection_prefix_end(value)
+    query_start = database_query_start(value, prefix_end)
+    return [value, nil] unless query_start
+
+    [value[0...query_start], value[(query_start + 1)..]]
+  end
+  private_class_method :database_connection_parts
+
+  def database_connection_prefix_end(value)
+    prefix = CONNECTION_URI_PREFIX.match(value)
+    return prefix.end(0) if prefix && !INVALID_PERCENT_ENCODING.match?(value)
+
+    raise ArgumentError,
+          'database_connection_string: base_connection_string is not a valid connection URL',
+          cause: nil
+  end
+  private_class_method :database_connection_prefix_end
+
+  def database_query_start(value, prefix_end)
+    userinfo_end = database_userinfo_end(value, prefix_end)
+    value.index('?', userinfo_end ? userinfo_end + 1 : prefix_end)
+  end
+  private_class_method :database_query_start
+
+  def database_userinfo_end(value, prefix_end)
+    authority_end = value.index('/', prefix_end)
+    userinfo_end = value.index('@', prefix_end)
+    return unless userinfo_end
+    return userinfo_end unless authority_end
+
+    userinfo_end if userinfo_end < authority_end
+  end
+  private_class_method :database_userinfo_end
+
+  def database_query_parameters(query)
+    return [] unless query
+
+    parameters = query.split('&', -1).reject do |parameter|
+      encoded_name = parameter.partition('=').first
+      URI::DEFAULT_PARSER.unescape(encoded_name) == 'application_name'
+    end
+    parameters.pop while parameters.last == ''
+    parameters
+  end
+  private_class_method :database_query_parameters
+
+  def database_application_name_query_value(user_id)
+    URI.encode_www_form_component(database_application_name(user_id)).gsub('+', '%20')
+  end
+  private_class_method :database_application_name_query_value
+
+  def database_application_name(user_id)
+    value = user_id.nil? ? '' : user_id.to_s
+    value.empty? ? FULL_ACCESS_APP_NAME : "#{USER_ACCESS_APP_NAME}:#{value}"
+  end
+  private_class_method :database_application_name
+end

data/lib/volcano/database.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Captures caller-owned query values before storing them in immutable builders.
+  module ImmutableQueryValue
+    module_function
+
+    def capture(value)
+      case value
+      when String then value.dup.freeze
+      when Array then value.map { |item| capture(item) }.freeze
+      when Hash then value.to_h { |key, item| [capture(key), capture(item)] }.freeze
+      else value
+      end
+    end
+  end
+  private_constant :ImmutableQueryValue
+
+  QueryContext = Data.define(:client, :transport, :database_name)
+  private_constant :QueryContext
+  QueryState = Data.define(:columns, :filters, :order, :limit, :offset)
+  private_constant :QueryState
+  EMPTY_QUERY_STATE = QueryState.new(
+    columns: [].freeze,
+    filters: [].freeze,
+    order: [].freeze,
+    limit: nil,
+    offset: nil
+  )
+  private_constant :EMPTY_QUERY_STATE
+
+  # Adds the shared immutable filter vocabulary to database builders.
+  module FilterMethods
+    def eq(column, value) = add_filter(column, 'eq', value)
+    def neq(column, value) = add_filter(column, 'neq', value)
+    def gt(column, value) = add_filter(column, 'gt', value)
+    def gte(column, value) = add_filter(column, 'gte', value)
+    def lt(column, value) = add_filter(column, 'lt', value)
+    def lte(column, value) = add_filter(column, 'lte', value)
+    def like(column, pattern) = add_filter(column, 'like', pattern)
+    def ilike(column, pattern) = add_filter(column, 'ilike', pattern)
+    def is(column, value) = add_filter(column, 'is', value)
+    def in(column, values) = add_filter(column, 'in', values)
+
+    private
+
+    def add_filter(column, operator, value)
+      condition = {
+        'column' => ImmutableQueryValue.capture(column),
+        'operator' => operator,
+        'value' => ImmutableQueryValue.capture(value)
+      }.freeze
+      copy(filters: [*@filters, condition])
+    end
+  end
+  private_constant :FilterMethods
+
+  # Creates immutable queries scoped to one project database.
+  class Database
+    def initialize(client, transport, name)
+      database_name = ImmutableQueryValue.capture(name)
+      @context = QueryContext.new(client:, transport:, database_name:)
+    end
+
+    def from(table)
+      QueryBuilder.new(@context, table)
+    end
+  end
+
+  # Builds and executes immutable database select queries.
+  class QueryBuilder
+    include FilterMethods
+
+    def initialize(context, table, state: EMPTY_QUERY_STATE)
+      @context = context
+      @table = ImmutableQueryValue.capture(table)
+      @columns = state.columns
+      @filters = state.filters
+      @order = state.order
+      @limit = state.limit
+      @offset = state.offset
+      freeze
+    end
+
+    def select(*columns)
+      copy(columns: ImmutableQueryValue.capture(columns))
+    end
+
+    def insert(values) = InsertBuilder.new(@context, @table, ImmutableQueryValue.capture(values))
+
+    def update(values)
+      UpdateBuilder.new(@context, @table, ImmutableQueryValue.capture(values), filters: @filters)
+    end
+
+    def delete
+      DeleteBuilder.new(@context, @table, filters: @filters)
+    end
+
+    def order(column, ascending: true)
+      clause = { 'column' => ImmutableQueryValue.capture(column), 'ascending' => ascending }.freeze
+      copy(order: [*@order, clause])
+    end
+
+    def limit(count)
+      copy(limit: count)
+    end
+
+    def offset(count)
+      copy(offset: count)
+    end
+
+    def execute
+      response = @context.client.session_request do |token|
+        Transport.invoke do
+          @context.transport.query_database_select(
+            authorization: token,
+            database_name: @context.database_name,
+            body: query_body
+          )
+        end
+      end
+      Transport.body(response, 200).fetch('data')
+    end
+
+    private
+
+    def copy(
+      columns: @columns,
+      filters: @filters,
+      order: @order,
+      limit: @limit,
+      offset: @offset
+    )
+      self.class.new(
+        @context,
+        @table,
+        state: QueryState.new(
+          columns: columns.freeze,
+          filters: filters.freeze,
+          order: order.freeze,
+          limit:,
+          offset:
+        )
+      )
+    end
+
+    def query_body
+      { 'table' => @table }.tap do |body|
+        body['select'] = @columns unless @columns.empty? || @columns == ['*']
+        body['filters'] = @filters unless @filters.empty?
+        body['order'] = @order unless @order.empty?
+        body['limit'] = @limit unless @limit.nil?
+        body['offset'] = @offset unless @offset.nil?
+      end
+    end
+  end
+
+  # Builds and executes an immutable database insert.
+  class InsertBuilder
+    def initialize(context, table, values)
+      @context = context
+      @table = table
+      @values = values
+      freeze
+    end
+
+    def execute
+      response = @context.client.session_request do |token|
+        Transport.invoke do
+          @context.transport.query_database_insert(
+            authorization: token,
+            database_name: @context.database_name,
+            body: { 'table' => @table, 'values' => @values }
+          )
+        end
+      end
+      Transport.body(response, 200).fetch('data')
+    end
+  end
+
+  # Builds and executes an immutable filtered database update.
+  class UpdateBuilder
+    include FilterMethods
+
+    def initialize(context, table, values, filters: [].freeze)
+      @context = context
+      @table = table
+      @values = values
+      @filters = filters
+      freeze
+    end
+
+    def execute
+      response = @context.client.session_request do |token|
+        Transport.invoke do
+          @context.transport.query_database_update(
+            authorization: token,
+            database_name: @context.database_name,
+            body: { 'table' => @table, 'values' => @values, 'filters' => @filters }
+          )
+        end
+      end
+      Transport.body(response, 200).fetch('data')
+    end
+
+    private
+
+    def copy(filters:)
+      self.class.new(@context, @table, @values, filters: filters.freeze)
+    end
+  end
+
+  # Builds and executes an immutable filtered database delete.
+  class DeleteBuilder
+    include FilterMethods
+
+    def initialize(context, table, filters: [].freeze)
+      @context = context
+      @table = table
+      @filters = filters
+      freeze
+    end
+
+    def execute
+      response = @context.client.session_request do |token|
+        Transport.invoke do
+          @context.transport.query_database_delete(
+            authorization: token,
+            database_name: @context.database_name,
+            body: { 'table' => @table, 'filters' => @filters }
+          )
+        end
+      end
+      Transport.body(response, 200).fetch('data')
+    end
+
+    private
+
+    def copy(filters:)
+      self.class.new(@context, @table, filters: filters.freeze)
+    end
+  end
+end

data/lib/volcano/errors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Volcano
+  module Error
+    # Base error containing structured Volcano response details.
+    class VolcanoError < StandardError
+      attr_reader :status, :code, :retry_after
+
+      def initialize(message, status: nil, code: nil, retry_after: nil)
+        super(message)
+        @status = status
+        @code = code
+        @retry_after = retry_after
+      end
+    end
+
+    class AuthenticationError < VolcanoError; end
+    class ValidationError < VolcanoError; end
+    class NotFoundError < VolcanoError; end
+    class ConflictError < VolcanoError; end
+
+    # Raised when an auth response arrives after the client session changes.
+    class SessionChangedError < ConflictError
+      def initialize(
+        message = 'Session changed during authentication operation',
+        status: 409,
+        code: 'auth_session_changed',
+        retry_after: nil
+      )
+        super
+      end
+    end
+
+    class RateLimitedError < VolcanoError; end
+    class ServerError < VolcanoError; end
+    class TransportError < VolcanoError; end
+  end
+end

data/lib/volcano/function_resolution.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Volcano
+  # Shared cache for function name resolution.
+  #
+  # GET /functions/resolve maps a function name to the identity and endpoint
+  # used to invoke it, and tells us how long that mapping stays valid. Without
+  # a cache every invocation pays that round trip. Entries are shared
+  # process-wide so separate clients against the same API reuse one resolution,
+  # and keyed by credential so a mapping never crosses an identity.
+  module FunctionResolution
+    Resolution = Data.define(:function_id, :invoke_url)
+
+    # A cached resolve result. A nil resolution is a remembered miss.
+    Outcome = Data.define(:resolution)
+
+    Entry = Data.define(:outcome, :expires_at)
+    private_constant :Entry
+
+    MAX_ENTRIES = 1024
+    NEGATIVE_TTL_SECONDS = 30
+
+    # Concurrent misses for one name serialize on a shared lock rather than
+    # each opening its own resolve. Striping keeps that bounded: a per-key lock
+    # table would grow with every name ever invoked.
+    LOCK_STRIPES = 64
+    private_constant :LOCK_STRIPES
+
+    @lock = Mutex.new
+    @entries = {}
+    @stripes = Array.new(LOCK_STRIPES) { Mutex.new }
+
+    class << self
+      # Returns the lock that serializes resolving one name.
+      def resolve_lock(api_url, authorization, name)
+        @stripes[[api_url, authorization, name].hash % LOCK_STRIPES]
+      end
+
+      # Returns an absolute invocation URL, or nil when unusable.
+      #
+      # The URL carries the caller's bearer token. Plaintext is accepted only
+      # when the API itself is plaintext, so a resolve response cannot
+      # downgrade a credential that is otherwise protected in transit.
+      def valid_invoke_url(value, api_url)
+        return nil unless value.is_a?(String) && !value.empty?
+
+        uri = URI.parse(value)
+        # URI accepts a port outside the range a connection can use.
+        return nil if uri.host.to_s.empty? || !uri.port.to_i.between?(1, 65_535)
+
+        usable_scheme?(uri.scheme, api_url) ? value : nil
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      # Returns the cached Outcome for a name, or nil when it must be resolved.
+      def lookup(api_url, authorization, name)
+        key = [api_url, authorization, name]
+        @lock.synchronize do
+          entry = @entries[key]
+          next nil if entry.nil?
+
+          if entry.expires_at <= now
+            @entries.delete(key)
+            next nil
+          end
+          entry.outcome
+        end
+      end
+
+      # Caches a resolution for the server-advertised lifetime.
+      def store(api_url, authorization, name, resolution, ttl_seconds)
+        write([api_url, authorization, name], Outcome.new(resolution: resolution), ttl_seconds)
+      end
+
+      # Remembers briefly that a name does not resolve, so a caller retrying an
+      # unknown name in a loop does not re-ask the server on every attempt.
+      def store_missing(api_url, authorization, name)
+        write([api_url, authorization, name], Outcome.new(resolution: nil), NEGATIVE_TTL_SECONDS)
+      end
+
+      # Drops one cached resolution that turned out to be stale.
+      def forget(api_url, authorization, name)
+        @lock.synchronize { @entries.delete([api_url, authorization, name]) }
+      end
+
+      # Drops every cached resolution. Used by specs for isolation.
+      def clear
+        @lock.synchronize { @entries.clear }
+      end
+
+      # The clock lifetimes are measured against, immune to wall-clock jumps.
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      private
+
+      def usable_scheme?(scheme, api_url)
+        case scheme&.downcase
+        when 'https' then true
+        when 'http' then URI.parse(api_url).scheme&.downcase == 'http'
+        else false
+        end
+      end
+
+      def write(key, outcome, ttl_seconds)
+        @lock.synchronize do
+          @entries[key] = Entry.new(outcome: outcome, expires_at: now + ttl_seconds)
+          next if @entries.size <= MAX_ENTRIES
+
+          @entries.delete_if { |_, entry| entry.expires_at <= now }
+          @entries.delete(@entries.min_by { |_, entry| entry.expires_at }&.first) while @entries.size > MAX_ENTRIES
+        end
+      end
+    end
+  end
+end

data/lib/volcano/function_response.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Immutable result of one function invocation.
+  FunctionResponse = Data.define(:data, :status, :headers, :version) do
+    def initialize(data:, status:, headers:, version:)
+      super(
+        data: immutable_json(data),
+        status: status,
+        headers: immutable_json(headers),
+        version: version&.dup&.freeze
+      )
+    end
+
+    private
+
+    def immutable_json(value)
+      case value
+      when Hash then value.to_h { |key, item| [immutable_json(key), immutable_json(item)] }.freeze
+      when Array then value.map { |item| immutable_json(item) }.freeze
+      when String then value.dup.freeze
+      else value
+      end
+    end
+  end
+end

data/lib/volcano/functions.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Volcano
+  # Invokes deployed Volcano functions by name.
+  class Functions
+    FUNCTION_NAME = /\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\z/
+    private_constant :FUNCTION_NAME
+
+    # Present only once the platform has dispatched to the function.
+    FUNCTION_INVOKED_HEADER = 'X-Volcano-Function-Invoked'
+    private_constant :FUNCTION_INVOKED_HEADER
+
+    def initialize(client, transport, api_url:)
+      @client = client
+      @transport = transport
+      @api_url = api_url
+    end
+
+    def invoke(name, payload = {})
+      validate_invocation(name, payload)
+      authorization = @client.function_token
+      resolution = resolve(authorization, name)
+      response = Transport.invoke { invoke_resolved(authorization, resolution, payload.dup) }
+      if stale_mapping?(response)
+        # The function was deleted and recreated, so the cached identity no
+        # longer exists. Resolve again before giving up.
+        FunctionResolution.forget(@api_url, authorization, name)
+        resolution = resolve(authorization, name)
+        response = Transport.invoke { invoke_resolved(authorization, resolution, payload.dup) }
+      end
+      function_response(response)
+    end
+
+    private
+
+    # A platform 404 means the cached function identity is gone. A function that
+    # answers 404 itself must be returned rather than retried: invoking twice
+    # would run the caller's side effects twice. The platform sets
+    # X-Volcano-Function-Invoked only after dispatch, so its absence is what
+    # separates the two. X-Volcano-Version cannot: the server stamps it on every
+    # response, including errors raised before the function is reached.
+    def stale_mapping?(response)
+      response.status == 404 && header(response.headers, FUNCTION_INVOKED_HEADER).nil?
+    end
+
+    def invoke_resolved(authorization, resolution, payload)
+      if resolution.invoke_url.nil?
+        @transport.invoke_function(
+          authorization: authorization, function_id: resolution.function_id, payload: payload
+        )
+      else
+        @transport.invoke_function_url(
+          authorization: authorization, invoke_url: resolution.invoke_url, payload: payload
+        )
+      end
+    end
+
+    # Returns the function's identity, reusing a live cached resolution.
+    def resolve(authorization, name)
+      cached = FunctionResolution.lookup(@api_url, authorization, name)
+      return cached_resolution(cached) if cached
+
+      # Hold the name's lock across the round trip so concurrent callers wait
+      # for one resolve instead of each opening their own.
+      FunctionResolution.resolve_lock(@api_url, authorization, name).synchronize do
+        cached = FunctionResolution.lookup(@api_url, authorization, name)
+        next cached_resolution(cached) if cached
+
+        resolve_uncached(authorization, name)
+      end
+    end
+
+    def resolve_uncached(authorization, name)
+      resolved = Transport.invoke do
+        @transport.resolve_function_for_invocation(authorization: authorization, name: name)
+      end
+      FunctionResolution.store_missing(@api_url, authorization, name) if resolved.status == 404
+      payload = Transport.body(resolved, 200)
+      resolution = resolved_resolution(payload)
+      FunctionResolution.store(@api_url, authorization, name, resolution, cache_ttl(payload))
+      resolution
+    end
+
+    def cached_resolution(cached)
+      return cached.resolution if cached.resolution
+
+      raise Error::NotFoundError.new('Function was not found', status: 404)
+    end
+
+    def validate_invocation(name, payload)
+      unless name.is_a?(String) && FUNCTION_NAME.match?(name)
+        raise ArgumentError,
+              'Function name must be DNS-safe: lowercase letters, numbers, and hyphens; 1-63 characters'
+      end
+      raise TypeError, 'Function payload must be a Hash' unless payload.is_a?(Hash)
+    end
+
+    def resolved_resolution(payload)
+      function_id = payload['function_id'] if payload.is_a?(Hash)
+      raise TypeError, 'Expected a complete function response' unless function_id.is_a?(String) && !function_id.empty?
+
+      # Absent when the deployment serves no public invocation domain, as in
+      # local development; the function is reached through the API instead.
+      FunctionResolution::Resolution.new(
+        function_id: function_id,
+        invoke_url: FunctionResolution.valid_invoke_url(payload['invoke_url'], @api_url)
+      )
+    end
+
+    def cache_ttl(payload)
+      ttl = payload['cache_ttl_seconds'] if payload.is_a?(Hash)
+      raise TypeError, 'Expected a complete function response' unless ttl.is_a?(Integer) && ttl.positive?
+
+      ttl
+    end
+
+    # A non-2xx the platform produced never reached the function, so it raises
+    # rather than being returned as the function's answer. That turns on the
+    # dispatch marker, not on the version stamp, which every response carries —
+    # keying on the stamp would hand back every platform failure as a reply.
+    def function_response(response)
+      version = header(response.headers, 'X-Volcano-Version')
+      dispatched = !header(response.headers, FUNCTION_INVOKED_HEADER).nil?
+      Transport.body(response, 200) unless response.status.between?(200, 299) || dispatched
+
+      FunctionResponse.new(
+        data: response.body, status: response.status,
+        headers: response.headers || {}, version: version
+      )
+    end
+
+    def header(headers, name)
+      headers&.find { |key, _| key.casecmp?(name) }&.last
+    end
+  end
+end