Waterfall API

get_capsule_id

get_capsule_id(): number

Returns this capsule's unique integer ID.

get_watermark_time

get_watermark_time(): number

Returns the nanoseconds elapsed since watermark start. The value is negative when the start lies in the future.

get_watermark_start_time

get_watermark_start_time(): number

Returns the watermark start as a Unix timestamp in nanoseconds.

set_watermark_start

set_watermark_start(offset_ns: number): void

Sets watermark start to capsule creation time plus offset_ns.

set_watermark_start_absolute

set_watermark_start_absolute(timestamp_ns: number): void

Sets watermark start from a Unix timestamp in nanoseconds.

stop

stop(): void

Shuts down the capsule.

get_parameter

get_parameter(name: string): any | nil

Returns a capsule parameter as declared in the manifest and defined in the policy.

broadcast_data

broadcast_data(scheme: string, name: string, field_name: string, values: any[], ...): void

Broadcasts a message to all peer nodes (as defined in the config). Supply one or more repeating field_name and values pairs; every value is converted to a string.

send_data

send_data(scheme: string, name: string, recipient: string, field_name: string, values: any[], ...): void

Sends a message to one peer node (as defined in the config). Supply one or more repeating field_name and values pairs; every value is converted to a string.

broadcast_message

broadcast_message(name: string, message: string): void

Broadcasts a message to all peer nodes (as defined in the config).

get_message

get_message(name: string, callback: function(message: string): void): void

Subscribes to messages (and matching data) and passes each one to the callback. The listener remains active until cancelled.

get_data

get_data(name: string, callback: function(data: table<string, string[]>): void): void

Subscribes to messages and passes each complete payload to the callback. The listener remains active until cancelled.

sleep

sleep(name: string, delay_ns: number): void

Blocks for the given duration.

sleep_until

sleep_until(name: string, watermark_time_ns: number): void

Blocks until the given offset from watermark start, returning immediately when that time has already passed.

on_time

on_time(name: string, watermark_time_ns: number, callback: function(): void): function(): void

Schedules a callback relative to watermark start time and returns a function that cancels the callback.

on_timeout

on_timeout(name: string, delay_ns: number, callback: function(): void): function(): void

Schedules a callback relative to current time and returns a function that cancels the callback.

on_interval

on_interval(name: string, interval_ns: number, callback: function(): void): function(): void

Runs a callback at an interval until the returned cancellation function is called. Callback execution time contributes to interval drift.

get_flows

get_flows(): table<string, Flow>

Returns all currently bound flows, keyed by their configured flow names.

cancel_event

cancel_event(name: string): void

Cancels active timers, monitors, listeners, flow bindings, and subscriptions registered under the given name.

bind_embedding_flow

bind_embedding_flow(name: string, flow_name: string, flow_class: FlowClass, callback: function(flows: Flow[]): void): void

Binds the first matching embedding flow, stores it as flow_name, and calls the callback, passing it the newly bound flow.

bind_detection_flow

bind_detection_flow(name: string, flow_name: string, flow_class: FlowClass, callback: function(flows: Flow[]): void): void

Binds the first matching detection flow, stores it as flow_name, and calls the callback, passing it the newly bound flow.

bind_flow

bind_flow(name: string, flow_name: string, flow_class: FlowClass, callback: function(flows: Flow[]): void): void

Deprecated alias of bind_embedding_flow.

detect_burst_interval

detect_burst_interval(name: string, duration_ns: number, precision_ns: number, minimum_packets: number, flows: string | string[], callback: function(start_time_ns: number): void): void

Calls the callback whenever the minimum packet amount is reached within the duration, which is sliding and may be slightly off depending on precision. The callback receives the start time of the burst window, relative to the watermark start time.

detect_silent_interval

detect_silent_interval(name: string, duration_ns: number, precision_ns: number, maximum_packets: number, flows: string | string[], callback: function(start_time_ns: number): void): void

Calls the callback whenever less or equal than the maximum packet amount is reached within the duration, which is sliding and may be slightly off depending on precision. The callback receives the start time of the silent window, relative to the watermark start time.

monitor_packet_count

monitor_packet_count(name: string, reporting_interval_ns: number, flows: string | string[], callback: function(count: number): void, at_timestamp_ns: number): void

Starts packet count monitoring at the Unix-nanosecond timestamp and reports the amount of packets seen in each interval.

monitor_data_throughput

monitor_data_throughput(name: string, reporting_interval_ns: number, flows: string | string[], callback: function(bytes: number): void, at_timestamp_ns: number): void

Starts data throughput monitoring at the Unix-nanosecond timestamp and reports the amount of bytes seen in each interval.

on_packet

on_packet(name: string, flows: string | string[], callback: function(packet: { window: number, seq_num: number, ack_num: number, window_scale: number, length: number } | { length: number, rtpSeqN: number }): void): void

Calls callback with a flat protocol-specific table for every packet passing through the given flows.

random_int

random_int(min: number, max: number): number

Returns a cryptographically random integer in the inclusive range from min through max.

random_bool

random_bool(): boolean

Returns a cryptographically random, evenly distributed boolean.

shuffle

shuffle(values: any[]): any[]

Returns a new cryptographically randomized permutation of the array without changing the input table.

submit_data

submit_data(scheme: string, field_name: string, values: any[], ...): void

Submits one or more repeating field_name and values pairs to the local correlation service. Every value is converted to a string.

get_rtt

get_rtt(name: string, data_flow: string, control_flow: string, callback: function(rtt_ns: number): void): void

Measures TCP round-trip time once, then passes it to the callback.

get_rtts

get_rtts(name: string, data_flow: string, control_flow: string, callback: function(rtt_ns: number): void): void

Continuously measures TCP round-trip times and calls callback for each sample.

time constants

Some numerical constants are made available, which represent their respective time frame in nanoseconds:

NANOSECOND, MICROSECOND, MILLISECOND, SECOND, MINUTE, HOUR

sync_start_time

sync_start_time(name: string, timeout_ns: number, sync_delay_ns: number, callback: function(): void): void

Synchronizes watermark start time with at least one detection capsule, then calls the callback. If synchronization does not complete before the timeout, the capsule is stopped.

get_key

get_key(scheme: string, key_list_name: string): any[]

Returns the next key from the prepared key list in the key directory. The key list cycles back to its first key after the last one is used.

add_to_action

add_to_action(flow_name: string, iptables_chain: string): void

Registers a bound flow with the action service in an iptables chain such as INPUT, OUTPUT, or FORWARD. Its initial action accepts packets.

broadcast_key

broadcast_key(scheme: string, key: number[], extra_data: table<string, any | any[]>): void

Broadcasts a key message containing scheme, key, and the additional fields. Key elements and scalar or array values in extra_data are transmitted as strings.

set_action_drop

set_action_drop(flow_name: string, options: { duration: number, start: number, amount: number }): void

Sets the flow to drop all packets. It starts at the Unix-second timestamp options.start or immediately if omitted, and lasts either options.duration nanoseconds long or until options.amount packets were dropped. If both limits are omitted, it is permanent.

set_action_delay

set_action_delay(flow_name: string, delay_ns: number, options: { duration: number, start: number, amount: number }): void

Sets the flow to delay all packets. It starts at the Unix-second timestamp options.start or immediately if omitted, and lasts either options.duration nanoseconds long or until options.amount packets were delayed. If both limits are omitted, it is permanent.

set_action_modify

set_action_modify(flow_name: string, header: string, value: string, options: { duration: number, start: number, amount: number }): void

Sets the flow to modify a header of all TCP packets. It starts at the Unix-second timestamp options.start or immediately if omitted, and lasts either options.duration nanoseconds long or until options.amount packets were modified. If both limits are omitted, it is permanent.

set_action_accept

set_action_accept(flow_name: string): void

Replaces the flow's current action with unconditional acceptance.

send_packet

send_packet(packet: string | { id: string }): void

Accepts and releases a packet buffered by on_packet_action. Pass either its packet ID or the callback's packet table containing id.

reinject_packet

reinject_packet(packet: string | { id: string }): void

Alias of send_packet.

on_packet_action

on_packet_action(name: string, flows: string | string[], callback: function(packet: { id: string, protocol: string, packet_len: number, data: { window: number, seq_num: number, ack_num: number, window_scale: number, length: number } | { length: number, checksum: number, rtpSeqN: number | nil } }): table | nil): void

Runs the decision callback for each packet on the selected flows.

Return nil, { action = "buffer" }, { action = "accept" }, { action = "drop" }, { action = "modify", header = "TcpWindow", value = string }, or { action = "delay", delay = number }, where delay is in nanoseconds.

sync_start_time

sync_start_time(name: string, timeout_ns: number, callback: function(): void): void

Synchronizes watermark start time with one embedding capsule, then calls the callback. If synchronization does not complete before the timeout, the capsule is stopped.

submit_key

submit_key(scheme: string, key: any[]): void

Converts the extracted key elements to strings and submits them to the correlation service.