class

RNS::Resource

Inherits Reference < Object

Handles large data transfers over Link instances using segmentation, sliding-window flow control, and adaptive rate adjustment. Data is split into parts, each verified by a map hash, and transmitted with automatic retry and congestion back-off. Supports compression, encryption, metadata, and multi-segment transfers for payloads that exceed a single advertisement.

Constants

ADVERTISED = 2_u8
ASSEMBLING = 5_u8
AUTO_COMPRESS_MAX_SIZE = (64 * 1024) * 1024
AWAITING_PROOF = 4_u8
COMPLETE = 6_u8
CORRUPT = 8_u8
FAILED = 7_u8
FAST_RATE_THRESHOLD = (WINDOW_MAX_SLOW - WINDOW) - 2
HASHMAP_IS_EXHAUSTED = 255_u8
HASHMAP_IS_NOT_EXHAUSTED = 0_u8

Flags indicating whether all hashmap segments have been delivered. ─── Hashmap flags ─────────────────────────────────────────────

MAPHASH_LEN = 4

Size limits governing part hashing, maximum transfer sizes, and the automatic compression threshold. ─── Size constants ────────────────────────────────────────────

MAX_ADV_RETRIES = 4
MAX_EFFICIENT_SIZE = ((1 * 1024) * 1024) - 1
MAX_RETRIES = 16
METADATA_MAX_SIZE = ((16 * 1024) * 1024) - 1
PART_TIMEOUT_FACTOR = 4

Timeout multipliers, retry budgets, and grace periods that govern how long to wait for parts/proofs before retransmitting or failing. ─── Timeout and retry constants ───────────────────────────────

PART_TIMEOUT_FACTOR_AFTER_RTT = 2
PER_RETRY_DELAY = 0.5
PROCESSING_GRACE = 1.0
PROOF_TIMEOUT_FACTOR = 3
QUEUED = 1_u8
RANDOM_HASH_SIZE = 4
RATE_FAST = (50 * 1000) / 8

Throughput thresholds (bytes/sec) used to classify the link speed and select the appropriate window ceiling. ─── Rate constants ────────────────────────────────────────────

RATE_VERY_SLOW = (2 * 1000) / 8
REJECTED = 0_u8
RESPONSE_MAX_GRACE_TIME = 10
RETRY_GRACE_TIME = 0.25
SDU = Packet::MDU
SENDER_GRACE_TIME = 10.0
STATUS_NONE = 0_u8

Transfer lifecycle states. Values are ordered so that status < COMPLETE means the transfer is still in progress. ─── Status constants ──────────────────────────────────────────

TRANSFERRING = 3_u8
VERY_SLOW_RATE_THRESHOLD = 2
WATCHDOG_MAX_SLEEP = 1.0
WINDOW = 4

Window parameters controlling how many unacknowledged parts may be in flight. The window grows or shrinks based on measured throughput (see FAST_RATE_THRESHOLD / VERY_SLOW_RATE_THRESHOLD). ─── Window constants ──────────────────────────────────────────

WINDOW_FLEXIBILITY = 4
WINDOW_MAX = WINDOW_MAX_FAST
WINDOW_MAX_FAST = 75
WINDOW_MAX_SLOW = 10
WINDOW_MAX_VERY_SLOW = 4
WINDOW_MIN = 2

Constructors

Class methods

accept(advertisement_packet : Packet, callback : Proc(Resource, Nil) | Nil = nil, progress_callback : Proc(Resource, Nil) | Nil = nil, request_id : Bytes | Nil = nil) : Resource | Nil

Accepts an incoming resource advertisement and constructs a receiver-side Resource. Initialises the hashmap, starts the watchdog fiber, and returns the new resource (or nil if the link is unavailable or a transfer for the same hash is already in progress).

Source
reject(advertisement_packet : Packet)

Declines an incoming resource advertisement by sending a RESOURCE_RCL packet back to the advertising peer. The resource is never allocated.

Source

Instance methods

_rejected
Source
adv_sent
Source
adv_sent=(adv_sent : Float64)
Source
assemble
Source
auto_compress
Source
auto_compress=(auto_compress : Bool)
Source
auto_compress_limit
Source
auto_compress_limit=(auto_compress_limit : Int64)
Source
auto_compress_option
Source
auto_compress_option=(auto_compress_option : Bool | Int64)
Source
callback
Source
callback=(callback : Proc(Resource, Nil) | Nil)
Source
cancel

Aborts the transfer if it has not already completed. Sends a RESOURCE_ICL cancel packet when this side is the initiator, deregisters the resource from the link, and invokes the callback.

Source
compressed
Source
compressed=(compressed : Bool)
Source
consecutive_completed_height
Source
consecutive_completed_height=(consecutive_completed_height : Int32)
Source
data
Source
data=(data : Bytes | Nil)
Source
eifr
Source
eifr=(eifr : Float64 | Nil)
Source
encrypted
Source
encrypted=(encrypted : Bool)
Source
expected_proof
Source
expected_proof=(expected_proof : Bytes)
Source
fast_rate_rounds
Source
fast_rate_rounds=(fast_rate_rounds : Int32)
Source
flags
Source
flags=(flags : UInt8)
Source
get_data_size
Source
get_hash
Source
get_map_hash(data : Bytes) : Bytes
Source
get_parts
Source
get_progress
Source
get_segment_progress
Source
get_segments
Source
get_transfer_size
Source
has_metadata
Source
has_metadata=(has_metadata : Bool)
Source
hash

Generates an UInt64 hash value for this object.

This method must have the property that a == b implies a.hash == b.hash.

The hash value is used along with == by the Hash class to determine if two objects reference the same hash key.

Subclasses must not override this method. Instead, they must define hash(hasher), though usually the macro def_hash can be used to generate this method.

Source
hash=(hash : Bytes)
Source
hashmap
Source
hashmap=(hashmap : Array(Bytes | Nil))
Source
hashmap_height
Source
hashmap_height=(hashmap_height : Int32)
Source
hashmap_raw_bytes

Hashmap (sender: concatenated bytes, receiver: array of Bytes?)

Source
hashmap_raw_bytes=(hashmap_raw_bytes : Bytes)

Hashmap (sender: concatenated bytes, receiver: array of Bytes?)

Source
hashmap_update(segment : Int32, hashmap_bytes : Bytes)
Source
hashmap_update_packet(plaintext : Bytes)
Source
hmu_retry_ok
Source
hmu_retry_ok=(hmu_retry_ok : Bool)
Source
initiator
Source
initiator=(initiator : Bool)
Source
is_compressed?
Source
is_response
Source
is_response=(is_response : Bool)
Source
last_activity
Source
last_activity=(last_activity : Float64)
Source
last_part_sent
Source
last_part_sent=(last_part_sent : Float64)
Source
max_adv_retries
Source
max_adv_retries=(max_adv_retries : Int32)
Source
max_retries
Source
max_retries=(max_retries : Int32)
Source
meta_storagepath
Source
meta_storagepath=(meta_storagepath : String)
Source
metadata
Source
metadata=(metadata : Bytes | Nil)
Source
metadata_size
Source
metadata_size=(metadata_size : Int32)
Source
original_hash
Source
original_hash=(original_hash : Bytes)
Source
outstanding_parts
Source
outstanding_parts=(outstanding_parts : Int32)
Source
part_timeout_factor
Source
part_timeout_factor=(part_timeout_factor : Float64)
Source
previous_eifr
Source
previous_eifr=(previous_eifr : Float64 | Nil)
Source
progress_callback_proc
Source
progress_callback_proc=(progress_callback_proc : Proc(Resource, Nil) | Nil)
Source
prove
Source
random_hash
Source
random_hash=(random_hash : Bytes)
Source
receive_part(packet : Packet)
Source
received_count
Source
received_count=(received_count : Int32)
Source
receiver_min_consecutive_height
Source
receiver_min_consecutive_height=(receiver_min_consecutive_height : Int32)
Source
receiver_parts

Receiver-side parts (nil or data bytes)

Source
receiver_parts=(receiver_parts : Array(Bytes | Nil))

Receiver-side parts (nil or data bytes)

Source
receiving_part
Source
receiving_part=(receiving_part : Bool)
Source
req_data_rtt_rate
Source
req_data_rtt_rate=(req_data_rtt_rate : Float64)
Source
req_hashlist
Source
req_hashlist=(req_hashlist : Array(Bytes))
Source
req_resp
Source
req_resp=(req_resp : Float64 | Nil)
Source
req_resp_rtt_rate
Source
req_resp_rtt_rate=(req_resp_rtt_rate : Float64)
Source
req_sent
Source
req_sent=(req_sent : Float64)
Source
req_sent_bytes
Source
req_sent_bytes=(req_sent_bytes : Int32)
Source
request(request_data : Bytes)
Source
request_id
Source
request_id=(request_id : Bytes | Nil)
Source
request_next
Source
retries_left
Source
retries_left=(retries_left : Int32)
Source
rtt=(rtt : Float64 | Nil)
Source
rtt_rxd_bytes
Source
rtt_rxd_bytes=(rtt_rxd_bytes : Int64)
Source
rtt_rxd_bytes_at_part_req
Source
rtt_rxd_bytes_at_part_req=(rtt_rxd_bytes_at_part_req : Int64)
Source
sdu=(sdu : Int32)
Source
segment_index
Source
segment_index=(segment_index : Int32)
Source
sender_grace_time
Source
sender_grace_time=(sender_grace_time : Float64)
Source
sender_parts

Sender-side parts (Packet objects with map_hash)

Source
sender_parts=(sender_parts : Array(Packet))

Sender-side parts (Packet objects with map_hash)

Source
sent_parts
Source
sent_parts=(sent_parts : Int32)
Source
set_callback(callback : Proc(Resource, Nil) | Nil)
Source
set_progress_callback(callback : Proc(Resource, Nil) | Nil)
Source
size
Source
size=(size : Int64)
Source
split
Source
split=(split : Bool)
Source
started_transferring
Source
started_transferring=(started_transferring : Float64 | Nil)
Source
status

─── Instance properties ───────────────────────────────────────

Source
status=(status : UInt8)

─── Instance properties ───────────────────────────────────────

Source
storagepath
Source
storagepath=(storagepath : String)
Source
timeout
Source
timeout=(timeout : Float64)
Source
timeout_factor
Source
timeout_factor=(timeout_factor : Float64)
Source
to_s(io : IO)

Appends a short String representation of this object which includes its class name and its object address.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).to_s # => #<Person:0x10a199f20>
Source
total_parts
Source
total_parts=(total_parts : Int32)
Source
total_segments
Source
total_segments=(total_segments : Int32)
Source
total_size
Source
total_size=(total_size : Int64)
Source
truncated_hash
Source
truncated_hash=(truncated_hash : Bytes)
Source
uncompressed_size
Source
uncompressed_size=(uncompressed_size : Int64)
Source
update_eifr
Source
validate_proof(proof_data : Bytes)
Source
very_slow_rate_rounds
Source
very_slow_rate_rounds=(very_slow_rate_rounds : Int32)
Source
waiting_for_hmu
Source
waiting_for_hmu=(waiting_for_hmu : Bool)
Source
watchdog_job
Source
watchdog_lock
Source
watchdog_lock=(watchdog_lock : Bool)
Source
window
Source
window=(window : Int32)
Source
window_flexibility
Source
window_flexibility=(window_flexibility : Int32)
Source
window_max
Source
window_max=(window_max : Int32)
Source
window_min
Source
window_min=(window_min : Int32)
Source