pg_ledger 0.1.0

data/lib/pg_ledger/models.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module PgLedger
+  def self.table_name_prefix
+    "pg_ledger_"
+  end
+
+  class Record < ActiveRecord::Base
+    self.abstract_class = true
+  end
+
+  class Ledger < Record
+    has_many :accounts
+    belongs_to :owner, polymorphic: true, optional: true
+    validates :name, presence: true
+
+    DEFAULT_ID = 1
+  end
+
+  class Account < Record
+    def self.resolve!(ref, currency: nil, ledger_id: Ledger::DEFAULT_ID)
+      case ref
+      when Account then ref
+      when String
+        scope = where(code: ref, ledger_id: ledger_id)
+        scope = scope.where(currency: currency.to_s.upcase) if currency
+        found = scope.limit(2).to_a
+        raise UnknownAccount, "no account with code #{ref.inspect}#{" (#{currency})" if currency} in ledger #{ledger_id}" if found.empty?
+        raise Error, "code #{ref.inspect} is ambiguous, pass the record or a currency:" if found.size > 1
+        found.first
+      else
+        raise ArgumentError, "account must be a PgLedger::Account or code String, got #{ref.class}"
+      end
+    end
+
+    belongs_to :ledger
+
+    belongs_to :owner, polymorphic: true, optional: true
+    has_many :debit_lines, class_name: "PgLedger::Line", foreign_key: :debit_account_id
+    has_many :credit_lines, class_name: "PgLedger::Line", foreign_key: :credit_account_id
+    has_many :balances, class_name: "PgLedger::Balance"
+
+    validates :code, :currency, presence: true
+    validates :normal_balance, inclusion: { in: %w[debit credit] }
+
+    # Balance-aware relation: each row responds to #current_balance, and the
+    # aggregate is filterable/sortable in SQL. Sharded accounts sum exactly.
+    #
+    #   PgLedger::Account.with_balance.where("current_balance > ?", 100_00)
+    #   PgLedger::Account.with_balance.order(current_balance: :desc).limit(10)
+    #
+    # A LATERAL subquery join (not GROUP BY) so it composes with any other
+    # where/order without dragging them into aggregate rules.
+    scope :with_balance, -> {
+      joins(<<~SQL)
+        JOIN LATERAL (
+          SELECT COALESCE(SUM(b.amount), 0) AS current_balance
+          FROM pg_ledger_balances b WHERE b.account_id = pg_ledger_accounts.id
+        ) balance_sum ON true
+      SQL
+        .select("pg_ledger_accounts.*, balance_sum.current_balance")
+    }
+
+    INTERVALS = %w[hour day week month].freeze
+    # Fixed-step buckets ("30 minutes", "6 hours") chart via date_bin;
+    # calendar units above stay on date_trunc (a month has no fixed step).
+    FIXED_STEP = /\A\d+\s+(minute|minutes|hour|hours)\z/
+
+    def balance(at: nil)
+      return balances.sum(:amount) unless at
+
+      # Watermark resolved separately and bound as a literal — a subquery here
+      # blinds the planner and turns the tail read into a seq scan. All day
+      # boundaries are computed by Postgres in its own timezone (rollup! cuts
+      # days the same way); Ruby's zone never enters the comparison.
+      sql = <<~SQL
+        SELECT
+          COALESCE((SELECT SUM(debits - credits) FROM pg_ledger_account_days
+                    WHERE account_id = :id
+                      AND day < LEAST(:wm_next::date, :at::timestamptz::date)), 0)
+          +
+          COALESCE((SELECT SUM(amount) FROM pg_ledger_lines
+                    WHERE debit_account_id = :id
+                      AND posted_at >= LEAST(:wm_next::date, :at::timestamptz::date)::timestamptz
+                      AND posted_at <= :at), 0)
+          -
+          COALESCE((SELECT SUM(amount) FROM pg_ledger_lines
+                    WHERE credit_account_id = :id
+                      AND posted_at >= LEAST(:wm_next::date, :at::timestamptz::date)::timestamptz
+                      AND posted_at <= :at), 0)
+      SQL
+      row = self.class.connection.select_rows(
+        self.class.sanitize_sql_array([sql, { id: id, at: at, wm_next: rollup_next_day }])
+      ).first
+      signed = Integer(row.first)
+      normal_balance == "debit" ? signed : -signed
+    end
+
+    # First un-rolled day, as a bare Date — bound into SQL and interpreted in
+    # Postgres' timezone, matching how rollup! truncates days.
+    def rollup_next_day
+      day = AccountDay.where(account_id: id).maximum(:day)
+      day ? day + 1 : Date.new(1970, 1, 1)
+    end
+
+    # Balance at the end of each bucket in [from, to] — chart-ready [[Time, Integer]].
+    # day/week/month read the daily rollups plus an un-rolled tail from lines;
+    # hour reads lines directly (rollups are daily). Exact for sharded accounts.
+    def balance_series(from:, to: Time.current, interval: "day")
+      interval = interval.to_s
+      fixed = interval.match?(FIXED_STEP)
+      unless fixed || INTERVALS.include?(interval)
+        raise ArgumentError,
+          "interval must be one of #{INTERVALS.join(", ")} or a fixed step like \"30 minutes\", got #{interval.inspect}"
+      end
+
+      # Bucket function: date_bin for fixed steps, date_trunc for calendar
+      # units. Both strings are chosen here, never from user input.
+      bucket = fixed ? "date_bin(:unit::interval, %s, 'epoch'::timestamptz)" : "date_trunc(:unit, %s)"
+      step = fixed ? ":unit::interval" : "('1 ' || :unit)::interval"
+
+      sign = normal_balance == "debit" ? "1" : "-1"
+      source =
+        if fixed || interval == "hour"
+          <<~SQL
+            day_rows AS (
+              SELECT l.posted_at AS ts, #{sign} * l.amount AS delta
+              FROM pg_ledger_lines l WHERE l.debit_account_id = :id
+              UNION ALL
+              SELECT l.posted_at, #{sign} * -l.amount
+              FROM pg_ledger_lines l WHERE l.credit_account_id = :id
+            )
+          SQL
+        else
+          <<~SQL
+            day_rows AS (
+              SELECT day::timestamptz AS ts, #{sign} * (debits - credits) AS delta
+              FROM pg_ledger_account_days WHERE account_id = :id
+              UNION ALL
+              SELECT date_trunc('day', l.posted_at), SUM(#{sign} * l.amount)
+              FROM pg_ledger_lines l
+              WHERE l.debit_account_id = :id AND l.posted_at >= :wm_next::date
+              GROUP BY 1
+              UNION ALL
+              SELECT date_trunc('day', l.posted_at), SUM(#{sign} * -l.amount)
+              FROM pg_ledger_lines l
+              WHERE l.credit_account_id = :id AND l.posted_at >= :wm_next::date
+              GROUP BY 1
+            )
+          SQL
+        end
+
+      sql = <<~SQL
+        WITH #{source},
+        buckets AS (
+          SELECT generate_series(
+            #{format(bucket, ":from::timestamptz")},
+            #{format(bucket, ":to::timestamptz")},
+            #{step}
+          ) AS bucket
+        ),
+        opening AS (
+          SELECT COALESCE(SUM(delta), 0) AS amount FROM day_rows
+          WHERE ts < #{format(bucket, ":from::timestamptz")}
+        ),
+        deltas AS (
+          SELECT #{format(bucket, "ts")} AS bucket, SUM(delta) AS delta
+          FROM day_rows
+          WHERE ts >= #{format(bucket, ":from::timestamptz")} AND ts <= :to
+          GROUP BY 1
+        )
+        SELECT b.bucket,
+               (SELECT amount FROM opening) +
+               COALESCE(SUM(d.delta) OVER (ORDER BY b.bucket ROWS UNBOUNDED PRECEDING), 0)
+        FROM buckets b
+        LEFT JOIN deltas d USING (bucket)
+        ORDER BY b.bucket
+      SQL
+      rows = self.class.connection.select_rows(self.class.sanitize_sql_array(
+        [sql, { unit: interval, from: from, to: to, id: id, wm_next: rollup_next_day }]
+      ))
+      rows.map { |bucket, amount| [bucket.to_time, Integer(amount)] }
+    end
+
+    # Debit/credit volume, total or per bucket. day/week/month buckets read the
+    # daily rollups + un-rolled tail; hour and totals read lines directly.
+    def turnover(from:, to: Time.current, interval: nil)
+      if interval.nil?
+        return {
+          debits: debit_lines.where(posted_at: from..to).sum(:amount),
+          credits: credit_lines.where(posted_at: from..to).sum(:amount)
+        }
+      end
+      if interval.to_s == "hour"
+        sql = <<~SQL
+          SELECT bucket, SUM(d), SUM(c) FROM (
+            SELECT date_trunc('hour', posted_at) AS bucket, SUM(amount) AS d, 0 AS c
+            FROM pg_ledger_lines WHERE debit_account_id = :id AND posted_at BETWEEN :from AND :to GROUP BY 1
+            UNION ALL
+            SELECT date_trunc('hour', posted_at), 0, SUM(amount)
+            FROM pg_ledger_lines WHERE credit_account_id = :id AND posted_at BETWEEN :from AND :to GROUP BY 1
+          ) t GROUP BY 1 ORDER BY 1
+        SQL
+        return self.class.connection.select_rows(self.class.sanitize_sql_array(
+          [sql, { id: id, from: from, to: to }]
+        )).map { |b, d, c| { period: b.to_time, debits: d.to_i, credits: c.to_i } }
+      end
+
+      interval = interval.to_s
+      unless INTERVALS.include?(interval)
+        raise ArgumentError, "interval must be one of #{INTERVALS.join(", ")}, got #{interval.inspect}"
+      end
+      sql = <<~SQL
+        WITH day_rows AS (
+          SELECT day::timestamptz AS ts, debits, credits
+          FROM pg_ledger_account_days WHERE account_id = :id
+          UNION ALL
+          SELECT date_trunc('day', l.posted_at), SUM(l.amount), 0
+          FROM pg_ledger_lines l
+          WHERE l.debit_account_id = :id AND l.posted_at >= :wm_next::date
+          GROUP BY 1
+          UNION ALL
+          SELECT date_trunc('day', l.posted_at), 0, SUM(l.amount)
+          FROM pg_ledger_lines l
+          WHERE l.credit_account_id = :id AND l.posted_at >= :wm_next::date
+          GROUP BY 1
+        )
+        SELECT date_trunc(:unit, ts) AS bucket, SUM(debits), SUM(credits)
+        FROM day_rows
+        WHERE ts >= date_trunc(:unit, :from::timestamptz) AND ts <= :to
+        GROUP BY 1 ORDER BY 1
+      SQL
+      rows = self.class.connection.select_rows(self.class.sanitize_sql_array(
+        [sql, { unit: interval, from: from, to: to, id: id, wm_next: rollup_next_day }]
+      ))
+      rows.map { |b, d, c| { period: b.to_time, debits: Integer(d), credits: Integer(c) } }
+    end
+  end
+
+  class Entry < Record
+    has_many :lines
+
+    validates :posted_at, presence: true
+
+    def readonly?
+      persisted?
+    end
+  end
+
+  class Line < Record
+    belongs_to :entry
+    belongs_to :debit_account, class_name: "PgLedger::Account"
+    belongs_to :credit_account, class_name: "PgLedger::Account"
+
+    validates :amount, numericality: { only_integer: true, greater_than: 0 }
+
+    def readonly?
+      persisted?
+    end
+  end
+
+  class Balance < Record
+    belongs_to :account
+  end
+
+  class AccountDay < Record
+    belongs_to :account
+  end
+end

data/lib/pg_ledger/posting.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module PgLedger
+  class Posting
+    CALL_SQL = <<~SQL
+      SELECT * FROM pg_ledger_post(?, ?, ?::jsonb, ?, ?::jsonb, ?::jsonb, ?, ?)
+    SQL
+
+    def initialize(legs:, idempotency_key:, metadata:, posted_at:, reverses: nil,
+                   shard_hint: nil, ledger_id: Ledger::DEFAULT_ID)
+      @legs = legs
+      @idempotency_key = idempotency_key
+      @metadata = metadata || {}
+      @posted_at = posted_at
+      @reverses = reverses
+      @shard_hint = shard_hint
+      @ledger_id = ledger_id
+    end
+
+    def call
+      prepare
+      rows = Entry.find_by_sql(
+        [CALL_SQL, @idempotency_key, digest, JSON.generate(@metadata), @posted_at,
+         JSON.generate(legs_payload), JSON.generate(deltas_payload), @reverses, @ledger_id]
+      )
+      rows.first
+    rescue ActiveRecord::StatementInvalid => e
+      raise Posting.map_pg_error(e)
+    end
+
+    # For Batch: everything the SQL function needs, no execution.
+    def payload
+      prepare
+      {
+        idempotency_key: @idempotency_key,
+        request_digest: digest,
+        metadata: @metadata,
+        posted_at: @posted_at,
+        reverses_entry_id: @reverses,
+        ledger_id: @ledger_id,
+        legs: legs_payload,
+        deltas: deltas_payload
+      }
+    end
+
+    ERROR_MARKERS = {
+      "pg_ledger:insufficient_balance" => :InsufficientBalance,
+      "pg_ledger:idempotency_conflict" => :IdempotencyConflict,
+      "pg_ledger:frozen_account" => :FrozenAccount,
+      "pg_ledger:period_closed" => :PeriodClosed,
+      "pg_ledger:over_reversal" => :OverReversal,
+      "pg_ledger:invalid_reversal" => :InvalidReversal,
+      "pg_ledger:cross_ledger" => :CrossLedger,
+      "is not balanced" => :Unbalanced,
+      "rows are immutable" => :ImmutableRecord
+    }.freeze
+
+    def self.map_pg_error(error)
+      ERROR_MARKERS.each do |marker, name|
+        return PgLedger.const_get(name).new(error.message) if error.message.include?(marker)
+      end
+      error
+    end
+
+    private
+
+    def prepare
+      return if @accounts
+
+      raise ArgumentError, "entry has no lines" if @legs.empty?
+      @accounts = @legs.to_h { |leg| [leg, Account.resolve!(leg.account_ref, ledger_id: @ledger_id)] }
+      check_balanced!
+      build_pairs
+      build_deltas
+    end
+
+    def check_balanced!
+      sums = Hash.new(0)
+      @legs.each do |leg|
+        sign = leg.direction == "debit" ? 1 : -1
+        sums[@accounts[leg].currency] += sign * leg.amount
+      end
+      unbalanced = sums.reject { |_, sum| sum.zero? }
+      return if unbalanced.empty?
+
+      raise Unbalanced, "entry does not balance: #{unbalanced.map { |cur, sum| "#{cur} off by #{sum}" }.join(", ")}"
+    end
+
+    # A journal row IS a balanced pair: debit_account -> credit_account in
+    # one currency. Builder legs are netted per (account, currency) first —
+    # a debit and a credit of the same account cancel — then greedily zipped
+    # into pairs. Netting is what makes decomposition total: net debits and
+    # net credits sum equal per currency (check_balanced! holds), so the zip
+    # always terminates with both sides empty.
+    def build_pairs
+      @pairs = []
+      by_currency = Hash.new { |h, k| h[k] = Hash.new(0) }
+      @legs.each do |leg|
+        account = @accounts[leg]
+        by_currency[account.currency][account] += (leg.direction == "debit" ? leg.amount : -leg.amount)
+      end
+      by_currency.each do |currency, nets|
+        debits = nets.select { |_, v| v.positive? }.map { |a, v| [a, v] }.sort_by { |a, _| a.id }
+        credits = nets.select { |_, v| v.negative? }.map { |a, v| [a, -v] }.sort_by { |a, _| a.id }
+        until debits.empty? || credits.empty?
+          d, c = debits.first, credits.first
+          amount = [d[1], c[1]].min
+          @pairs << { debit: d[0], credit: c[0], currency: currency, amount: amount }
+          d[1] -= amount
+          c[1] -= amount
+          debits.shift if d[1].zero?
+          credits.shift if c[1].zero?
+        end
+      end
+      raise ArgumentError, "entry nets to nothing" if @pairs.empty?
+    end
+
+    # One delta row per account; sharded accounts get one random shard per
+    # posting, chosen here so batches can pre-lock every touched row. A batch
+    # passes a shared shard_hint so all its postings hit the SAME shard per
+    # account — otherwise a large batch touches every shard and concurrent
+    # batches serialize on the pre-lock union.
+    def build_deltas
+      @deltas = {}
+      @pairs.each do |pair|
+        [[pair[:debit], "debit"], [pair[:credit], "credit"]].each do |account, side|
+          sign = (side == account.normal_balance) ? 1 : -1
+          delta = (@deltas[account.id] ||= {
+            account_id: account.id,
+            shard: pick_shard(account),
+            delta: 0,
+            min_balance: account.min_balance
+          })
+          delta[:delta] += sign * pair[:amount]
+        end
+      end
+    end
+
+    def pick_shard(account)
+      shards = account.balance_shards
+      return 0 if shards <= 1
+
+      @shard_hint ? [(@shard_hint * shards).floor, shards - 1].min : rand(shards)
+    end
+
+    def legs_payload
+      @pairs.map do |pair|
+        { debit_account_id: pair[:debit].id, credit_account_id: pair[:credit].id,
+          currency: pair[:currency], amount: pair[:amount] }
+      end
+    end
+
+    def deltas_payload
+      @deltas.values
+    end
+
+    def digest
+      @digest ||= Digest::SHA256.hexdigest(
+        JSON.generate(
+          pairs: @pairs.map { |p| [p[:debit].id, p[:credit].id, p[:currency], p[:amount]] },
+          metadata: @metadata,
+          reverses: @reverses
+        )
+      )
+    end
+  end
+end

data/lib/pg_ledger/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PgLedger
+  class Railtie < Rails::Railtie
+    # The models load via ActiveSupport.on_load(:active_record); in an app
+    # that reaches PgLedger.* before touching ActiveRecord (a rake task, a
+    # console one-liner) that hook may not have fired yet — trigger it.
+    config.after_initialize do
+      ActiveRecord::Base if defined?(ActiveRecord)
+    end
+  end
+end

data/lib/pg_ledger/version.rb

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