antd 0.2.0 → 0.3.0

data/lib/antd/grpc_client.rb

@@ -17,6 +17,8 @@ require_relative "v1/chunks_services_pb"
 require_relative "v1/files_services_pb"
 require_relative "v1/upload_services_pb"
 require_relative "v1/wallet_services_pb"
+require_relative "v1/pointers_services_pb"
+require "base64"
 
 module Antd
   DEFAULT_GRPC_TARGET = "localhost:50051"
@@ -47,6 +49,7 @@ module Antd
       @file_stub   = Antd::V1::FileService::Stub.new(target, :this_channel_is_insecure)
       @upload_stub = Antd::V1::UploadService::Stub.new(target, :this_channel_is_insecure)
       @wallet_stub = Antd::V1::WalletService::Stub.new(target, :this_channel_is_insecure)
+      @pointer_stub = Antd::V1::PointerService::Stub.new(target, :this_channel_is_insecure)
     end
 
     # --- Health ---
@@ -468,8 +471,183 @@ module Antd
       resp.approved
     end
 
+    # --- Pointers ---
+    #
+    # The same methods, models and errors as the REST +Client+ (see there),
+    # over PointerService. The pointer errors share gRPC status codes with
+    # older ones, so the daemon names them in the +x-antd-error-code+
+    # trailer, which +grpc_call+ reads (see +Antd.error_for_grpc_metadata+).
+    # Unset optionals arrive as "" or an absent message and read as nil, as
+    # REST's nulls do. Every write pays: do not retry +pointer_create+,
+    # +pointer_update+, +pointer_transfer+ or +pointer_finalize+
+    # automatically.
+
+    # Mirrors +Client#pointer_keys+.
+    # @return [Array<String>]
+    def pointer_keys
+      resp = grpc_call { @pointer_stub.list_keys(Antd::V1::ListPointerKeysRequest.new) }
+      resp.keys.map(&:address)
+    end
+
+    # Mirrors +Client#pointer_create+. Pays; do not retry automatically.
+    # @return [PointerWriteResult]
+    def pointer_create(owner, target, kind: nil)
+      req = Antd::V1::PointerWriteRequest.new(owner: owner, target: target, kind: kind.to_s)
+      pointer_write_result(grpc_call { @pointer_stub.create(req) })
+    end
+
+    # Mirrors +Client#pointer_update+. Pays; do not retry automatically.
+    # @return [PointerWriteResult]
+    def pointer_update(owner, target, kind: nil)
+      req = Antd::V1::PointerWriteRequest.new(owner: owner, target: target, kind: kind.to_s)
+      pointer_write_result(grpc_call { @pointer_stub.update(req) })
+    end
+
+    # Mirrors +Client#pointer_transfer+. Pays; do not retry automatically.
+    # @return [PointerTransferResult]
+    def pointer_transfer(owner, recipient)
+      req = Antd::V1::PointerTransferRequest.new(owner: owner, recipient: recipient)
+      resp = grpc_call { @pointer_stub.transfer(req) }
+      PointerTransferResult.new(
+        address: resp.address,
+        state_id: resp.state_id,
+        finality: resp.finality.nil? ? nil : pointer_finality_from(resp.finality),
+        finality_error: presence(resp.finality_error)
+      )
+    end
+
+    # Mirrors +Client#pointer_get+.
+    # @return [PointerRecord]
+    def pointer_get(address)
+      resp = grpc_call { @pointer_stub.get(Antd::V1::GetPointerRequest.new(address: address)) }
+      PointerRecord.new(
+        address: resp.address,
+        owner: resp.owner,
+        counter: Antd.parse_pointer_counter("counter", resp.counter),
+        kind: resp.kind,
+        kind_tag: resp.kind_tag,
+        target: resp.target,
+        state_id: resp.state_id,
+        is_final: resp.is_final,
+        transferred_to: presence(resp.transferred_to)
+      )
+    end
+
+    # Mirrors +Client#pointer_resolve+.
+    # @return [PointerTarget]
+    def pointer_resolve(address)
+      resp = grpc_call { @pointer_stub.resolve(Antd::V1::ResolvePointerRequest.new(address: address)) }
+      PointerTarget.new(kind: resp.kind, kind_tag: resp.kind_tag, target: resp.target)
+    end
+
+    # Mirrors +Client#pointer_finality+.
+    # @return [PointerFinality]
+    def pointer_finality(address)
+      resp = grpc_call { @pointer_stub.finality(Antd::V1::PointerFinalityRequest.new(address: address)) }
+      pointer_finality_from(resp)
+    end
+
+    # Mirrors +Client#pointer_controller+.
+    # @return [PointerController]
+    def pointer_controller(address)
+      resp = grpc_call { @pointer_stub.controller(Antd::V1::PointerControllerRequest.new(address: address)) }
+      PointerController.new(pointer: resp.pointer, transfers: resp.transfers.to_a, frozen: resp.frozen)
+    end
+
+    # Mirrors +Client#pointer_prepare+.
+    # @return [PointerPrepareResult]
+    def pointer_prepare(owner, op, target: nil, kind: nil, recipient: nil, include_signed_quotes: false)
+      req = Antd::V1::PreparePointerRequest.new(
+        owner: owner,
+        op: op.to_s,
+        target: target.to_s,
+        kind: kind.to_s,
+        recipient: recipient.to_s,
+        include_signed_quotes: include_signed_quotes ? true : false
+      )
+      resp = grpc_call { @pointer_stub.prepare(req) }
+      PointerPrepareResult.new(
+        upload_id: resp.upload_id,
+        op: resp.op,
+        address: resp.address,
+        state_id: resp.state_id,
+        counter: Antd.parse_pointer_counter("counter", resp.counter),
+        payment_type: resp.payment_type,
+        payments: resp.payments.map do |p|
+          PaymentInfo.new(quote_hash: p.quote_hash, rewards_address: p.rewards_address, amount: p.amount)
+        end,
+        total_amount: resp.total_amount,
+        payment_vault_address: resp.payment_vault_address,
+        payment_token_address: resp.payment_token_address,
+        rpc_url: resp.rpc_url,
+        # Bytes on the wire; base64 here, the same form REST returns.
+        signed_quotes: resp.signed_quotes.map do |q|
+          SignedQuoteEntry.new(
+            quote_hash: q.quote_hash,
+            quote: Base64.strict_encode64(q.quote),
+            commitment_sidecar: q.commitment_sidecar.empty? ? nil : Base64.strict_encode64(q.commitment_sidecar)
+          )
+        end
+      )
+    end
+
+    # Mirrors +Client#pointer_finalize+. A +CloseGroupShortfallError+ with
+    # +retryable+ means the daemon kept the paid state: repeat the call with
+    # the same +upload_id+.
+    # @return [PointerFinalizeResult]
+    def pointer_finalize(upload_id, tx_hashes)
+      req = Antd::V1::FinalizePointerRequest.new(upload_id: upload_id, tx_hashes: tx_hashes)
+      resp = grpc_call { @pointer_stub.finalize(req) }
+      PointerFinalizeResult.new(
+        address: resp.address,
+        state_id: resp.state_id,
+        counter: Antd.parse_pointer_counter("counter", resp.counter),
+        finality: resp.finality.nil? ? nil : pointer_finality_from(resp.finality)
+      )
+    end
+
     private
 
+    def pointer_write_result(resp)
+      PointerWriteResult.new(
+        address: resp.address,
+        state_id: resp.state_id,
+        counter: Antd.parse_pointer_counter("counter", resp.counter)
+      )
+    end
+
+    # Converts the proto finality, where an unset counter or transferred_to is
+    # "" and an unset state or majority an absent message: each reads as nil.
+    def pointer_finality_from(f)
+      PointerFinality.new(
+        address: f.address,
+        group: f.group,
+        answered: f.answered,
+        status: f.status,
+        counter: f.counter.empty? ? nil : Antd.parse_pointer_counter("finality counter", f.counter),
+        state: f.state.nil? ? nil : pointer_final_state_from(f.state),
+        states: f.states.map { |s| pointer_final_state_from(s) },
+        majority: f.majority.nil? ? nil : pointer_final_state_from(f.majority),
+        transferred_to: presence(f.transferred_to)
+      )
+    end
+
+    def pointer_final_state_from(s)
+      PointerFinalState.new(
+        state_id: s.state_id,
+        kind: s.kind,
+        kind_tag: s.kind_tag,
+        target: s.target,
+        holders: s.holders,
+        transferred_to: presence(s.transferred_to)
+      )
+    end
+
+    # A proto string, or nil when unset (empty).
+    def presence(value)
+      value.nil? || value.empty? ? nil : value
+    end
+
     # Drives a +return_op: true+ server-streaming call, yielding +DownloadFrame+s.
     # The byte denominator is surfaced first as a leading +DownloadFrame+ (its
     # +meta+ set), read from the response's +x-content-length+ initial metadata;
@@ -560,8 +738,21 @@ module Antd
 
 
     # Executes a gRPC call and translates errors to Antd error types.
+    #
+    # The daemon's +x-antd-error-code+ trailer comes first: where it names a
+    # code that shares its gRPC status with older errors (POINTER_FINAL,
+    # POINTER_FORKED, CONFLICT, CLOSE_GROUP_SHORTFALL) and agrees with the
+    # status code, it selects the typed error. Anything else is re-raised to
+    # the status-code mapping below.
     def grpc_call
-      yield
+      begin
+        yield
+      rescue GRPC::BadStatus => e
+        tagged = Antd.error_for_grpc_metadata(e.code, e.details, e.message, e.metadata)
+        raise tagged unless tagged.nil?
+
+        raise
+      end
     rescue GRPC::InvalidArgument => e
       raise BadRequestError, e.message
     rescue GRPC::NotFound => e

data/lib/antd/grpc_manifests.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "manifests"
+require_relative "grpc_client"
+require_relative "v1/manifests_services_pb"
+
+# The manifest methods on +Antd::GrpcClient+, over ManifestService. The
+# models and the entry check are in manifests.rb, shared with REST.
+module Antd
+  # Channel arguments for the manifest stub's own channel. grpc-ruby has no
+  # per-call message limit, so ManifestService gets a channel of its own
+  # with both limits raised to +MANIFEST_GRPC_MAX_MESSAGE+; the other
+  # services keep gRPC's defaults.
+  MANIFEST_GRPC_CHANNEL_ARGS = {
+    "grpc.max_receive_message_length" => MANIFEST_GRPC_MAX_MESSAGE,
+    "grpc.max_send_message_length" => MANIFEST_GRPC_MAX_MESSAGE
+  }.freeze
+
+  class GrpcClient
+    # --- Manifests ---
+    #
+    # The same methods and models as the REST +Client+ (see there). The
+    # `.ant` bytes travel raw over gRPC; REST's base64 never shows. Unset
+    # optionals (proto3 +optional+ without a value, or an empty string) read
+    # as nil, as REST's omitted fields do.
+
+    # Mirrors +Client#build_manifest+. Nothing is paid for.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @return [BuiltManifest]
+    # @raise [BadRequestError] an entry with both or neither of +data_map+ and
+    #   +address+, or a bad +size+, before anything is sent
+    # @raise [BadRequestError] an entry the daemon rejects (INVALID_ARGUMENT);
+    #   the message names +entries[i]+
+    def build_manifest(entries, name: nil, torrent_info_hashes: nil, embed_roots: true)
+      inputs = Antd.manifest_entry_inputs(entries)
+      req = Antd::V1::BuildManifestRequest.new(
+        torrent_info_hashes: Array(torrent_info_hashes),
+        # Always sent, so "unset means true" never depends on the daemon.
+        embed_roots: embed_roots ? true : false,
+        entries: inputs.map { |e| manifest_entry_input_pb(e) }
+      )
+      req.name = name unless name.nil? || name.empty?
+
+      resp = grpc_call { manifest_stub.build(req) }
+      BuiltManifest.new(
+        manifest: resp.manifest,
+        link: manifest_pb_string(resp.link),
+        entries: resp.entries.map { |e| manifest_entry_info_from_pb(e) }
+      )
+    end
+
+    # Mirrors +Client#decode_manifest+. The bytes are sent raw.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @return [DecodedManifest]
+    def decode_manifest(manifest, resolve: false)
+      raise BadRequestError, MANIFEST_DECODE_NEEDS_INPUT if manifest.nil? || manifest.empty?
+
+      decode_manifest_pb(Antd::V1::DecodeManifestRequest.new(manifest: manifest.b, resolve: resolve ? true : false))
+    end
+
+    # Mirrors +Client#decode_manifest_link+.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @return [DecodedManifest]
+    def decode_manifest_link(link, resolve: false)
+      raise BadRequestError, MANIFEST_DECODE_NEEDS_INPUT if link.nil? || link.empty?
+
+      decode_manifest_pb(Antd::V1::DecodeManifestRequest.new(link: link, resolve: resolve ? true : false))
+    end
+
+    private
+
+    # ManifestService on its own channel, with +MANIFEST_GRPC_CHANNEL_ARGS+.
+    # Made on first use, so +initialize+ stays as it is.
+    def manifest_stub
+      @manifest_stub ||= Antd::V1::ManifestService::Stub.new(
+        @target, :this_channel_is_insecure, channel_args: MANIFEST_GRPC_CHANNEL_ARGS
+      )
+    end
+
+    def decode_manifest_pb(req)
+      resp = grpc_call { manifest_stub.decode(req) }
+      DecodedManifest.new(
+        source: resp.source,
+        name: resp.has_name? ? manifest_pb_string(resp.name) : nil,
+        torrent_info_hash_v1: manifest_pb_string(resp.torrent_info_hash_v1),
+        torrent_info_hash_v2: manifest_pb_string(resp.torrent_info_hash_v2),
+        entries: resp.entries.map { |e| manifest_entry_info_from_pb(e) }
+      )
+    end
+
+    def manifest_entry_input_pb(e)
+      attrs = {}
+      attrs[:path] = e.path unless e.path.nil? || e.path.empty?
+      attrs[:size] = e.size unless e.size.nil?
+      if e.data_map.nil? || e.data_map.empty?
+        attrs[:address] = e.address
+      else
+        attrs[:data_map] = e.data_map
+      end
+      Antd::V1::ManifestEntryInput.new(**attrs)
+    end
+
+    # proto3 +optional+ sizes are checked for presence: unset is nil, not 0.
+    def manifest_entry_info_from_pb(e)
+      ManifestEntryInfo.new(
+        effective_name: e.effective_name,
+        path: e.has_path? ? manifest_pb_string(e.path) : nil,
+        size: e.has_size? ? e.size : nil,
+        kind: e.kind,
+        content_address: e.content_address,
+        data_map: manifest_pb_string(e.data_map),
+        exact_size: e.has_exact_size? ? e.exact_size : nil,
+        error: manifest_pb_string(e.error)
+      )
+    end
+
+    # A proto string, or nil when empty.
+    def manifest_pb_string(value)
+      value.nil? || value.empty? ? nil : value
+    end
+  end
+end

data/lib/antd/manifests.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require "base64"
+require_relative "models"
+require_relative "errors"
+require_relative "client"
+
+# Manifests (ADR-0006): `.ant` files and `ant://` links that describe a set
+# of files, each with an optional path and size and either an embedded
+# DataMap or a public DataMap address. The daemon builds and decodes them
+# through ant-core, so callers never re-implement the format. Nothing is
+# uploaded or paid for.
+#
+# This file holds the models and the REST methods on +Antd::Client+;
+# grpc_manifests.rb adds the same methods to +Antd::GrpcClient+.
+module Antd
+  # +ManifestEntryInfo#kind+ values.
+  module ManifestEntryKind
+    # The manifest carries the entry's DataMap: it is the key to the file.
+    EMBEDDED = "embedded"
+    # The manifest carries a public file's DataMap address.
+    PUBLIC   = "public"
+  end
+
+  # +DecodedManifest#source+ values.
+  module ManifestSource
+    # `.ant` bytes or an `ant://manifest/` link.
+    MANIFEST  = "manifest"
+    # A file link or bare address, reported as one public entry with no path.
+    FILE_LINK = "file_link"
+  end
+
+  # One file for +build_manifest+. Set exactly one of +data_map+ or
+  # +address+; a Hash with the same keys works too.
+  #
+  # - +path+: the relative path the entry extracts under, subject to the
+  #   portable path rules. nil: it extracts under its content address.
+  # - +size+: the plaintext size to record, as given (the creator's claim).
+  #   nil: none is recorded; readers take the exact size from an embedded
+  #   root DataMap.
+  # - +data_map+: a hex DataMap, as the upload methods return it. The entry
+  #   embeds it.
+  # - +address+: a public file's DataMap address (hex, 32 bytes).
+  ManifestEntryInput = Struct.new(:path, :size, :data_map, :address, keyword_init: true) do
+    def initialize(path: nil, size: nil, data_map: nil, address: nil)
+      super
+    end
+  end
+
+  # What a manifest says about one entry. Unset fields are nil on both
+  # transports (REST omits them; gRPC sends no value or an empty string),
+  # so a +size+ or +exact_size+ the manifest lacks is nil, never 0.
+  #
+  # - +effective_name+: +path+, or the content address in hex when there is
+  #   none.
+  # - +path+: the entry's path, or nil.
+  # - +size+: the size recorded in the manifest (the creator's claim), or nil.
+  # - +kind+: a +ManifestEntryKind+ string.
+  # - +content_address+: hex. The file's public DataMap address, whether or
+  #   not it was ever made public; the same for private and public uploads
+  #   of one file.
+  # - +data_map+: the embedded DataMap in the hex form the download methods
+  #   accept. Decode only; nil for public entries.
+  # - +exact_size+: the exact plaintext size, from an embedded root DataMap
+  #   or after a resolving decode; nil when unknown.
+  # - +error+: why a resolving decode failed for this entry, or nil. A
+  #   failed entry does not fail the call.
+  ManifestEntryInfo = Struct.new(
+    :effective_name, :path, :size, :kind, :content_address, :data_map, :exact_size, :error,
+    keyword_init: true
+  ) do
+    def initialize(effective_name: "", path: nil, size: nil, kind: "", content_address: "",
+                   data_map: nil, exact_size: nil, error: nil)
+      super
+    end
+  end
+
+  # Result of +build_manifest+.
+  #
+  # - +manifest+: the `.ant` bytes (a binary String).
+  # - +link+: the `ant://manifest/` link, or nil when it would not fit the
+  #   recommended 1,500 bytes.
+  # - +entries+: +ManifestEntryInfo+s in encoded order (sorted by effective
+  #   name).
+  BuiltManifest = Struct.new(:manifest, :link, :entries, keyword_init: true)
+
+  # Result of +decode_manifest+ and +decode_manifest_link+.
+  #
+  # - +source+: a +ManifestSource+ string.
+  # - +name+: the suggested root directory name, or nil.
+  # - +torrent_info_hash_v1+, +torrent_info_hash_v2+: hex, or nil when absent.
+  # - +entries+: +ManifestEntryInfo+s.
+  DecodedManifest = Struct.new(
+    :source, :name, :torrent_info_hash_v1, :torrent_info_hash_v2, :entries,
+    keyword_init: true
+  )
+
+  # The gRPC message ceiling for manifest calls, both ways: a manifest can be
+  # 64 MiB, and a decode response carries its DataMaps in hex. gRPC's default
+  # receive limit is 4 MiB.
+  MANIFEST_GRPC_MAX_MESSAGE = 256 * 1024 * 1024
+
+  # The daemon's cap on the entry errors one 400 names.
+  MANIFEST_MAX_REPORTED_ENTRY_ERRORS = 20
+  private_constant :MANIFEST_MAX_REPORTED_ENTRY_ERRORS
+
+  # The daemon's message for empty decode input (empty bytes or link).
+  MANIFEST_DECODE_NEEDS_INPUT = "needs a manifest (base64 .ant bytes) or a link"
+
+  # Normalises +build_manifest+ entries to +ManifestEntryInput+s before
+  # anything is sent. A refusal is the +BadRequestError+ (400) the daemon
+  # would send, with its wording: every bad entry (both or neither of
+  # +data_map+ and +address+, nil and "" counting as unset; or a +size+ that
+  # is not a non-negative Integer) is collected and named as
+  # "N invalid entries: entries[i]: ...; entries[j]: ..." (at most 20, then
+  # "; and K more").
+  #
+  # @api private
+  # @param entries [Array<ManifestEntryInput, Hash>]
+  # @return [Array<ManifestEntryInput>]
+  # @raise [BadRequestError]
+  def self.manifest_entry_inputs(entries)
+    raise BadRequestError, "entries must be an Array" unless entries.is_a?(Array)
+
+    errors = []
+    inputs = entries.each_with_index.map do |e, i|
+      e = ManifestEntryInput.new(**e.transform_keys(&:to_sym)) if e.is_a?(Hash)
+      unless e.is_a?(ManifestEntryInput)
+        errors << "entries[#{i}]: must be a ManifestEntryInput or Hash"
+        next
+      end
+
+      has_data_map = !(e.data_map.nil? || e.data_map.empty?)
+      has_address = !(e.address.nil? || e.address.empty?)
+      if has_data_map && has_address
+        errors << "entries[#{i}]: give data_map or address, not both"
+      elsif !has_data_map && !has_address
+        errors << "entries[#{i}]: needs a data_map or an address"
+      end
+      unless e.size.nil? || (e.size.is_a?(Integer) && e.size >= 0)
+        errors << "entries[#{i}]: size must be a non-negative Integer or nil"
+      end
+      e
+    rescue ArgumentError
+      # A Hash with a key ManifestEntryInput does not have.
+      errors << "entries[#{i}]: unknown field (expected path, size, data_map, address)"
+      nil
+    end
+    raise BadRequestError, Antd.manifest_entry_errors_message(errors) unless errors.empty?
+
+    inputs
+  end
+
+  # The daemon's +entry_errors_message+.
+  #
+  # @api private
+  def self.manifest_entry_errors_message(errors)
+    shown = errors.first(MANIFEST_MAX_REPORTED_ENTRY_ERRORS).join("; ")
+    message = "#{errors.length} invalid entries: #{shown}"
+    message += "; and #{errors.length - MANIFEST_MAX_REPORTED_ENTRY_ERRORS} more" if errors.length > MANIFEST_MAX_REPORTED_ENTRY_ERRORS
+    message
+  end
+
+  class Client
+    # --- Manifests ---
+
+    # Build a `.ant` manifest from DataMaps and public addresses already in
+    # hand (POST /v1/manifests/build). Nothing is uploaded or paid for.
+    #
+    # By default the daemon resolves each shrunk DataMap's root (fetching its
+    # wrapper records) and embeds it when it is at most 64 KiB, so recipients
+    # skip that fetch (ADR-0006's policy). That reads from the network, so the
+    # call can time out; it is safe to retry.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @param entries [Array<ManifestEntryInput, Hash>] each with exactly one
+    #   of +data_map+ or +address+; checked before anything is sent
+    # @param name [String, nil] suggested root directory name (one portable
+    #   path component)
+    # @param torrent_info_hashes [Array<String>, nil] BitTorrent info hashes
+    #   of the same files: hex, 40 characters for v1 and/or 64 for v2
+    # @param embed_roots [Boolean] false embeds shrunk DataMaps exactly as
+    #   given (the wire's +embed_roots+; default true)
+    # @return [BuiltManifest]
+    # @raise [BadRequestError] an entry with both or neither of +data_map+ and
+    #   +address+, or a bad +size+, worded as the daemon words it
+    # @raise [BadRequestError] an entry the daemon rejects; the message names
+    #   +entries[i]+
+    def build_manifest(entries, name: nil, torrent_info_hashes: nil, embed_roots: true)
+      inputs = Antd.manifest_entry_inputs(entries)
+      wire = inputs.map do |e|
+        m = {}
+        m[:path] = e.path unless e.path.nil? || e.path.empty?
+        m[:size] = e.size unless e.size.nil?
+        if e.data_map.nil? || e.data_map.empty?
+          m[:address] = e.address
+        else
+          m[:data_map] = e.data_map
+        end
+        m
+      end
+      body = { entries: wire, embed_roots: embed_roots ? true : false }
+      body[:name] = name unless name.nil? || name.empty?
+      hashes = Array(torrent_info_hashes)
+      body[:torrent_info_hashes] = hashes unless hashes.empty?
+
+      j = do_json(:post, "/v1/manifests/build", body)
+      BuiltManifest.new(
+        manifest: manifest_bytes_from_b64(j["manifest"]),
+        link: manifest_string(j["link"]),
+        entries: manifest_entry_infos(j["entries"])
+      )
+    end
+
+    # Decode `.ant` bytes (POST /v1/manifests/decode). With +resolve+, the
+    # daemon fetches each entry's DataMap (and wrapper records) to report
+    # +exact_size+ and confirm the DataMap is on the network; content chunks
+    # are not fetched, and one entry's failure is reported in its +error+,
+    # not as a failed call. Nothing is paid for; safe to retry.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @param manifest [String] the `.ant` bytes
+    # @param resolve [Boolean]
+    # @return [DecodedManifest]
+    # @raise [BadRequestError] an empty +manifest+
+    # @raise [BadRequestError] bytes that are not a manifest
+    def decode_manifest(manifest, resolve: false)
+      raise BadRequestError, MANIFEST_DECODE_NEEDS_INPUT if manifest.nil? || manifest.empty?
+
+      post_manifest_decode({ manifest: b64_encode(manifest), resolve: resolve ? true : false })
+    end
+
+    # Decode an `ant://` manifest link, file link or bare 64-hex address
+    # (POST /v1/manifests/decode). See +decode_manifest+ for +resolve+.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @param link [String]
+    # @param resolve [Boolean]
+    # @return [DecodedManifest]
+    # @raise [BadRequestError] an empty +link+
+    # @raise [BadRequestError] a link the daemon cannot read
+    def decode_manifest_link(link, resolve: false)
+      raise BadRequestError, MANIFEST_DECODE_NEEDS_INPUT if link.nil? || link.empty?
+
+      post_manifest_decode({ link: link, resolve: resolve ? true : false })
+    end
+
+    private
+
+    def post_manifest_decode(body)
+      j = do_json(:post, "/v1/manifests/decode", body)
+      DecodedManifest.new(
+        source: j["source"] || "",
+        name: manifest_string(j["name"]),
+        torrent_info_hash_v1: manifest_string(j["torrent_info_hash_v1"]),
+        torrent_info_hash_v2: manifest_string(j["torrent_info_hash_v2"]),
+        entries: manifest_entry_infos(j["entries"])
+      )
+    end
+
+    # The build response's base64 `.ant` bytes, raw.
+    def manifest_bytes_from_b64(value)
+      b64_decode(value.to_s)
+    rescue ArgumentError => e
+      raise InternalError, "build_manifest: manifest is not valid base64: #{e.message}"
+    end
+
+    def manifest_entry_infos(raw)
+      return [] unless raw.is_a?(Array)
+
+      raw.filter_map do |e|
+        next unless e.is_a?(Hash)
+
+        ManifestEntryInfo.new(
+          effective_name: e["effective_name"] || "",
+          path: manifest_string(e["path"]),
+          size: manifest_size(e["size"]),
+          kind: e["kind"] || "",
+          content_address: e["content_address"] || "",
+          data_map: manifest_string(e["data_map"]),
+          exact_size: manifest_size(e["exact_size"]),
+          error: manifest_string(e["error"])
+        )
+      end
+    end
+
+    # An optional size: a JSON integer, or nil when absent (never 0).
+    def manifest_size(value)
+      value.is_a?(Integer) && value >= 0 ? value : nil
+    end
+
+    # An optional string: nil when absent or empty.
+    def manifest_string(value)
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+  end
+end