Hi, Thanks for writing this draft spec. Please see my suggested changes below:
That's a fine name. You can leave out the "Document" if you want.
It doesn't matter, so let's use semantic versioning: * the original torflow format was 1.0.0 * the format in this spec adds the "version" feature, so it is 1.1.0 (it is compatible with 1.0.0, as long as parsers ignore unrecognised lines)
It looks like 0.2.4.12-alpha added measured bandwidths
You could use the definition in the man page: "the bandwidth-authority generated file storing information on relays' measured bandwidth capacities"
This line is a copy-paste error, it should be deleted.
This file format gets the fingerprint and nickname from the consensus, so you should reference dir-spec.txt. (dir-list-spec.txt gets relay fingerprints and nicknames from Onionoo. That's why it uses the Onionoo definitions.) Here are the definitions of hexdigest (fingerprint) and nickname:
"optional" is not relevant in a definition. Let's delete this line, it's already documented as optional later on.
bw is not defined in dir-spec.txt. And the formatting is confusing. Double quotes are used for ASCII literal strings in dir-spec.txt. Can you please follow the format used in dir-spec.txt? Here is one example: Here's how you can define bw using the Int definition from dir-spec.txt: bw = Int bw is the aggregated measured bandwidth of this relay, in kilobytes per second.
dir-spec.txt
Our newest spec uses "version" for the file format version: and call it "version". I suggest: * use "version" for the file format version (or don't use "version") * use "source" for the implementation software name and version Please fix the formatting of this definition to be like dir-spec.txt. This definition has two arguments separated by spaces, the name, and the version.
"if absent" is not relevant in a definition. Let's move these lines to the header section. The software version should be optional. Torflow does not have a version, so we cannot require a version.
Please fix the formatting of this definition to be like dir-spec.txt.
We should say if order matters. We should say how new items get added to the header. (We could say that parsers MUST ignore unrecognised lines.)
The sbws sample data has: 1523911758 version=0.1.0 The first line does not have a "timestamp" string literal. The second line has an equals sign. The second line is optional (see the torflow sample data). Does Tor ignore the version line? If it does, we should document it.
You should say that order on a line doesn't matter, and relay order also doesn't matter.
The format has equals signs, but this definition does not.
It might be easier to say that each line allows extra arguments, and reference the dir-spec.txt definition: But does each argument need an equals sign?
This definition belongs in the definition section. Please fix the formatting of this definition to be like dir-spec.txt.
The format has equals signs, but this definition does not. The fingerprints in the sample data have $ signs. Does Tor require them? Or are they optional? We should document it either way.
The equals signs are correct here.
The format has equals signs, but this definition does not.
slice is not defined, just use "timestamp", then explain using the next line.
Is it worth explaining the difference?
Tor does not contain the string "measured_at": For consistency, please remove "measured_at", or add "updated_at".
We should think about which torflow fields are worth documenting. Maybe the sample data should contain more than one relay?
T |
_______________________________________________ tor-dev mailing list tor-dev@xxxxxxxxxxxxxxxxxxxx https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev