From 678aa7fb1f3055fbe5bc0a585448a71e788db10b Mon Sep 17 00:00:00 2001 From: Terts Diepraam Date: Mon, 4 Nov 2024 23:08:19 +0100 Subject: [PATCH] stelline: document the syntax a bit in the readme --- src/stelline/README.md | 114 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) diff --git a/src/stelline/README.md b/src/stelline/README.md index fe9491768..b60f52253 100644 --- a/src/stelline/README.md +++ b/src/stelline/README.md @@ -19,3 +19,117 @@ In both cases real `net::client` instances handle interaction with the server. When using a mock server the replay file should define both test requests and test responses and the mock server replies with the test responses. When using a real server the replay file defines DNS requests and server configuration and real `net::server` instances reply based on their configuration. + +## Syntax of an `.rpl` file + + +The replay format used by Stelline is a line based configuration. The format supports line comments starting with `;`. + +The format contains two sections `CONFIG` and `SCENARIO`. The format of the `CONFIG` section depends on how Stelline is used (e.g. as a client or as a server). The `CONFIG` section extends from the start of the file until the line containing the `CONFIG_END` option. + +The `SCENARIO` section contains the steps to perform in the test. It starts with `SCENARIO_BEGIN` and ends with `SCENARIO_END`. Note that all `.rpl` files must end with `SCENARIO_END`. + +### Steps +A scenario consists of steps. Each step is something that is executed in the test. A step can be one of the following types: + +- `QUERY` +- `CHECK_ANSWER` +- `TIME_PASSES` +- `TRAFFIC` (TODO) +- `CHECK_TEMP_FILE` (TODO) +- `ASSIGN` (TODO) + +In general, the syntax looks like: + +``` +STEP id type data +``` + +where `id` is a positive integer, `type` on of the step types mentioned above, and `data` is the data for the step. + +Steps of types `QUERY` and `CHECK_ANSWER` have entries associated with them, which are textual representations of DNS messages. These entries are simply put aafter the `STEP` declaration. + +A `QUERY` step sends a query to the tested program. It can optionally have data declaring its `ADDRESS` and `KEY`: + +``` +STEP 1 QUERY +STEP 1 QUERY ADDRESS KEY +``` + +A `CHECK_ANSWER` step checks an incoming answer. It has no data, only entries. + +``` +STEP 1 CHECK_ANSWER +``` + +A `TIME_PASSES` step increments the fake system clock by the specified number of seconds. The time is given after the `ELAPSE` token. + +``` +STEP 1 TIME_PASSES ELAPSE +``` + +### Entries + +An entry represents a DNS message (or an expected DNS message). It starts with `ENTRY_BEGIN` and ends with `ENTRY_END`. There are several parts to an entry, which depend on the use of the entry. The simplest form is the form used the `QUERY` step: + +``` +ENTRY_BEGIN +REPLY +SECTION + ... +SECTION + ... +... +ENTRY_END +``` + +The `REPLY` part specifies the header information of the outgoing message. The supported values are: + + - RCODES: `NOERROR`, `FORMERR`, `SERVFAIL`, `NXDOMAIN`, `NOTIMP`, `REFUSED`, `YXDOMAIN`, `YXRRSET`, `NXRRSET`, `NOTAUTH`, `NOTZONE`, `BADVERS`, `BADCOOKIE`. + - Flags: `AA`, `AD`, `CD`, `DO`, `QR`, `RA`, `RD`, `TC`, `NOTIFY`. + +The `SECTION` directives specify which sections to fill with each section with. The content of a section is exactly like a zonefile, except for the question section, which does not require rdata. + +There are two other sections in an entry, which are only relevant to ranges (see below), which are `MATCH` and `ADJUST`. The `MATCH` directive specifies which parts of the incoming message must match the reply to match the entry. The following values are allowed: + +- `all`: same as `opcode qtype qname rcode flags answer authority additional` +- `opcode` +- `qname` +- `rcode` +- Flags: `AD`, `CD`, `DO`, `RD`, `flags` +- `question`: same as `qtype qname` +- Sections: `answer`, `authority`, `additional` +- `subdomain` +- `ttl` +- Protocol: `TCP`, `UDP` +- `server_cookie` +- `ednsdata` +- `MOCK_CLIENT` +- `CONNECTION_CLOSED` +- `EXTRA_PACKETS` +- `ANY_ANSWER` + +The `ADJUST` directive specifies which parts of the incoming message should be changed before sending. The possible values are `copy_id` and `copy_query`. + +### Ranges + +Mock responses from are defined by a `RANGE`, which specifies the reponses that are given to a "range" of queries. A range is delimited by the `RANGE_BEGIN` and `RANGE_END` tokens. + +The `RANGE_BEGIN` directive takes two positive integers: a start and end value. A `QUERY` step with an id within that range can match this range. + +After the numeric range, a range has a list of addresses that match on this range, with each address on its own line prefixed with `ADDRESS`. + +Lastly, a range contains a list of entries, following the syntax described above. + +``` +RANGE_BEGIN 0 100 ; begin and end of the range + ADDRESS 1.1.1.1 ; an address to match + ADDRESS 2.2.2.2 ; a second address, any number of address is allowed + +ENTRY_BEGIN +; ... +ENTRY_END + +; more entries may be added +RANGE_END +```