Glossary

Runtime Target

One discovered Xray runtime selected by PID, container identity, or another stable runtime-local selector.

Runtime-Local

Scoped to one selected runtime target. The same tag or IP rule on another runtime is a different subject.

Speed Limiter Family

The product-facing identity RayLimit uses to select traffic: ip, inbound, or outbound.

Subject

The concrete runtime-scoped object a limiter request refers to, such as one runtime-local shared all-IP baseline, one runtime-local evidence-expanded all-IP selection, one specific IP, one inbound tag, or one outbound tag.

Baseline

For the IP family, the runtime-local shared all-IP default created by --ip all --rate ... or explicitly by --ip all --ip-aggregation shared --rate ....

IP Aggregation

For --ip all, the all-IP mode selected by --ip-aggregation. shared is the default. per_ip expands the current live client IP evidence into concrete specific-IP work.

Override

For the IP family, a specific --ip <ip> --rate ... rule that takes priority over the runtime-local shared baseline for that address.

Unlimited Exception

For the IP family, a specific --ip <ip> --unlimited rule that bypasses the runtime-local shared baseline for that address.

Dry-Run

The default mode where RayLimit plans and reports without mutating the host.

Execute

The explicit live-mutation mode enabled with --execute.

Observation

The host-state inspection step that checks whether the relevant tc and nftables state exists and whether it can be compared safely.

Reconcile

The process of comparing desired state to observed state and deciding whether the correct outcome is apply, no_op, replace, or remove.

Replace

A reconcile decision meaning the selected subject already has applied state, but that state differs from the desired state and needs replacement. In operator language this is the reapply path.

No-Op

A result where the observed managed state already matches the requested state, so no further change is needed.

Concrete Execution

A state where RayLimit has enough trustworthy evidence to attach traffic honestly and mutate the host.

Blocked By Design

An explicit safety verdict that stops live mutation when the current selector or observed state is not trustworthy enough.

Direct Attachment

A packet-facing tc attachment path that does not depend on an auxiliary mark-restoration backend. The IP family uses this model.

Mark-Backed Attachment

A path where nftables classifies traffic or restores marks and tc fw attaches the marked traffic to the selected class. Inbound and outbound use this model when the selector is concrete.

Managed State

The tc and related backend objects that RayLimit can attribute to one selected subject and therefore reconcile or remove conservatively.

RuntimeIdentity

The basic identity RayLimit records for a discovered runtime, including its name and detected binary basename. The binary name feeds prefix-match detection and binary-name resolution. See Runtime Targeting.

Sanaei Fork

A fork of Xray whose binaries are named sanaei* (for example sanaei-linux-amd64). RayLimit detects it through the sanaei / sanaei-core prefixes and applies fork-specific behavior, such as the StatsUserOnline requirement.

StatsService

The Xray API service that exposes traffic and connection statistics. It must be present in the config's api.services array for API-backed evidence.

StatsUserOnline

A companion Xray API service that the Sanaei fork requires (in addition to StatsService) before live online-user queries return evidence. When it is absent on a detected fork, RayLimit reports a typed StatsUserOnline service not enabled error instead of a silent no-sessions result.

Mark Attachment

The path where nftables classifies traffic or restores a packet mark and tc fw attaches the marked traffic to the selected class. Inbound and outbound use this model when the selector is concrete. Its apply path reconciles against observed state, which is what makes re-applying directions safe.

Idempotent Apply

The property that re-applying an already-satisfied limit makes no destructive change. RayLimit achieves this through reconcile-aware apply plus an execution-time backstop that treats an "already exists" managed root qdisc as success rather than an error.

Plain-Text tc Fallback

RayLimit prefers JSON (tc -j / nft -j) output but auto-detects when a binary ignores the flag and emits plain text, falling back to a plain-text parser. This keeps state inspection working on hosts whose tc/nft lack JSON support.