[tor-commits] [torspec/main] dir-spec: Merge prop328 into main specifications

[dgoulet at torproject.org]

commit 2b0093c2c972853e5c2c6bc9e41dc83a4a2e7793
Author: David Goulet <dgoulet at torproject.org>
Date:   Mon Nov 1 14:44:43 2021 -0400

    dir-spec: Merge prop328 into main specifications
    
    Signed-off-by: David Goulet <dgoulet at torproject.org>
---
 dir-spec.txt | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/dir-spec.txt b/dir-spec.txt
index 543e341..5076366 100644
--- a/dir-spec.txt
+++ b/dir-spec.txt
@@ -955,6 +955,75 @@ Table of Contents
 
        [Before Tor 0.4.5.1-alpha, this field was optional.]
 
+   "overload-general" SP version SP YYYY-MM-DD HH:MM:SS NL
+
+       [At most once.]
+
+       Indicate that the relay is overloaded due to one or many conditions
+       listed in proposal 328 section 1.1.
+
+       The timestamp is always rounded to the hour indicating when was the last
+       time the relay detected an overloaded state.
+
+       The 'version' field is a versioning field and is set to '1'. See prop328
+       for what consists of an overload state.
+
+       This field remains in place for 72 hours since last triggered. If the
+       limits are reached again in this period, the timestamp is updated, and
+       this 72 hour period restarts.
+
+       This indicator is not persistent on disk meaning that if the relay
+       restarts, the overload state is reset and disappear from the descriptor.
+
+       [Introduced in version 0.4.6.1-alpha]
+
+   "overload-ratelimits" SP version SP YYYY-MM-DD SP HH:MM:SS
+                         SP rate-limit SP burst-limit
+                         SP read-overload-count SP write-overload-count NL
+
+       [At most once.]
+
+       Indiate that the relay read or write rate limits were reached which is
+       a specific overload signal.
+
+       The 'version' field is a versioning field and is set to '1'.
+
+       The '{rate|burst}-limit' are respectively the torrc options
+       'BandwidthBurst' and 'BandwidthRate' limits set by the relay. In other
+       words, they are the bandwidth limitations of the relay.
+
+       The "{read|write}-overload-count" are the counts of how many times the
+       reported limits of burst/rate were exhausted and thus the maximum
+       between the read and write count occurrences. To make the counter more
+       meaningful and to avoid multiple connections saturating the counter when
+       a relay is overloaded, we only increment it once a minute.
+
+       They span from the past 24 hours starting at the provided timestamp
+       rounded down to the hour.
+
+       These counters are not persistent on disk meaning that if the relay
+       restarts, the overload state is reset and disappear from the descriptor.
+
+       [Introduced in version 0.4.6.1-alpha]
+
+   "overload-fd-exhausted" SP version YYYY-MM-DD HH:MM:SS NL
+
+       [At most once.]
+
+       As the overloaded line, the timestamp indicates that the maximum of file
+       descriptors was reached between this timestamp and the "published"
+       timestamp of the document.
+
+       This overload field remains in place for 72 hours since last triggered.
+       If the limits are reached again in this period, the timestamp is
+       updated, and this 72 hour period restarts.
+
+       The 'version' field is a versioning field and is set to '1'.
+
+       This indicator is not persistent on disk meaning that if the relay
+       restarts, the overload state is reset and disappear from the descriptor.
+
+       [Introduced in version 0.4.6.1-alpha]
 
 2.1.2. Extra-info document format