Add spec files for CLI Options

bin/spec/cmdline-opts/format.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+import sys
+from option import Option
+
+"""
+Format option file
+"""
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("usage: format.py OPTION_FILE")
+        sys.exit(1)
+    for option_file in sys.argv[1:]:
+        option = Option.parse_file(option_file)
+        open(option_file, "w").write(str(option) + "\n")
+
+
+if __name__ == "__main__":
+    main()

bin/spec/cmdline-opts/option.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+from typing import *
+
+
+class Option:
+    def __init__(
+        self,
+        name,
+        long,
+        short,
+        value,
+        value_default,
+        value_parser,
+        help,
+        conflict,
+        append,
+        deprecated,
+        description,
+    ):
+        self.name = name
+        self.long = long
+        self.short = short
+        self.value = value
+        self.value_default = value_default
+        self.value_parser = value_parser
+        self.help = help
+        self.conflict = conflict
+        self.append = append
+        self.deprecated = deprecated
+        self.description = description
+
+    def __eq__(self, other):
+        if not isinstance(other, Option):
+            return False
+        return (
+            self.name == other.name
+            and self.long == other.long
+            and self.short == other.short
+            and self.value == other.value
+            and self.value_default == other.value_default
+            and self.value_parser == other.value_parser
+            and self.help == other.help
+            and self.conflict == other.conflict
+            and self.append == other.append
+            and self.deprecated == other.deprecated
+            and self.description == other.description
+        )
+
+    def __str__(self):
+        s = "name: " + self.name
+        s += "\nlong: " + self.long
+        if self.short is not None:
+            s += "\nshort: " + self.short
+        if self.value is not None:
+            s += "\nvalue: " + self.value
+        if self.value_default is not None:
+            s += "\nvalue_default: " + self.value_default
+        if self.value_parser is not None:
+            s += "\nvalue_parser: " + self.value_parser
+        if self.help is not None:
+            s += "\nhelp: " + self.help
+        if self.conflict is not None:
+            s += "\nconflict: " + self.conflict
+        if self.append:
+            s += "\nmulti: append"
+        if self.deprecated:
+            s += "\ndeprecated: true"
+        s += "\n---"
+        s += "\n" + self.description
+        return s
+
+    def __hash__(self):
+        return hash(
+            (
+                self.name,
+                self.long,
+                self.short,
+                self.value,
+                self.value_default,
+                self.value_parser,
+                self.help,
+                self.conflict,
+                self.append,
+                self.description,
+            )
+        )
+
+    @staticmethod
+    def parse(s):
+        name = None
+        long = None
+        short = None
+        value = None
+        value_default = None
+        value_parser = None
+        help = None
+        conflict = None
+        append = False
+        deprecated = False
+        description = ""
+        in_description = False
+
+        for line in s.split("\n"):
+            if line.startswith("---"):
+                in_description = True
+            elif in_description:
+                description += line + "\n"
+            else:
+                key, v = parse_key_value(line)
+                if key == "name":
+                    name = v
+                elif key == "long":
+                    long = v
+                elif key == "short":
+                    short = v
+                elif key == "value":
+                    value = v
+                elif key == "value_default":
+                    value_default = v
+                elif key == "value_parser":
+                    value_parser = v
+                elif key == "help":
+                    help = v
+                elif key == "conflict":
+                    conflict = v
+                elif key == "multi":
+                    if v == "append":
+                        append = True
+                elif key == "deprecated":
+                    if v == "true":
+                        deprecated = True
+                    elif v == "false":
+                        deprecated = False
+                    else:
+                        raise Exception(
+                            "Expected true or false for deprecated attribute"
+                        )
+                else:
+                    raise Exception("Invalid attribute " + key)
+
+        if name is None:
+            raise Exception("missing name attribute")
+
+        if long is None:
+            raise Exception("missing long attribute")
+
+        return Option(
+            name,
+            long,
+            short,
+            value,
+            value_default,
+            value_parser,
+            help,
+            conflict,
+            append,
+            deprecated,
+            description.strip(),
+        )
+
+    @staticmethod
+    def parse_file(filename):
+        import sys
+
+        sys.stderr.write("Parsing " + filename + "\n")
+        s = open(filename).read()
+        return Option.parse(s)
+
+
+def parse_key_value(s) -> tuple[str, str]:
+    if ":" not in s:
+        raise Exception("Expecting key value")
+    index = s.index(":")
+    key = s[:index].strip()
+    value = s[index + 1 :].strip()
+    return key, value

bin/spec/cmdline-opts/parser.test.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+import unittest
+
+from option import Option, parse_key_value
+
+
+class OptionParserTest(unittest.TestCase):
+    def test_parse_key_value(self):
+        self.assertTrue(parse_key_value("xx") is None)
+        self.assertEqual(parse_key_value("a: b"), ("a", "b"))
+
+    def test_parse_connect_timeout(self):
+        option = Option.parse(
+            """name: connect_timeout
+long: connect-timeout
+value: SECONDS
+value_default: 300
+value_parser: u64
+help: Maximum time allowed for connection
+---
+Maximum time in seconds that you allow Hurl’s connection to take.
+
+See also -m, --max-time.
+"""
+        )
+        print(option)
+        self.assertEqual(
+            Option(
+                name="connect_timeout",
+                long="connect-timeout",
+                short=None,
+                value="SECONDS",
+                value_default="300",
+                value_parser="u64",
+                help="Maximum time allowed for connection",
+                conflict=None,
+                append=False,
+                deprecated=False,
+                description="Maximum time in seconds that you allow Hurl’s connection to take.\n\nSee also -m, --max-time.",
+            ),
+            option,
+        )
+
+    def test_parse_connect_to(self):
+        option = Option.parse(
+            """name: connect_to
+long: connect-to
+value: HOST1:PORT1:HOST2:PORT2
+help: For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead
+multi: append
+---
+For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead.
+"""
+        )
+        print(option)
+        self.assertEqual(
+            Option(
+                name="connect_to",
+                long="connect-to",
+                short=None,
+                value="HOST1:PORT1:HOST2:PORT2",
+                value_default=None,
+                value_parser=None,
+                help="For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead",
+                conflict=None,
+                append=True,
+                deprecated=False,
+                description="For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead.",
+            ),
+            option,
+        )
+
+    def test_fail_at_end(self):
+        option = Option.parse(
+            """name: fail_at_end
+long: fail-at-end
+help: Fail at end
+deprecated: true
+---
+
+    """
+        )
+        print(option)
+        self.assertEqual(
+            Option(
+                name="fail_at_end",
+                long="fail-at-end",
+                short=None,
+                value=None,
+                value_parser=None,
+                value_default=None,
+                help="Fail at end",
+                conflict=None,
+                append=False,
+                deprecated=True,
+                description="",
+            ),
+            option,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

docs/spec/cmdline-opts-hurl/aws_sigv4.option

@@ -0,0 +1,10 @@
+name: aws_sigv4
+long: aws-sigv4
+value: PROVIDER1[:PROVIDER2[:REGION[:SERVICE]]]
+help: Use AWS V4 signature authentication in the transfer
+---
+Generate an `Authorization` header with an AWS SigV4 signature.
+
+Use [`-u, --user`](#user) to specify Access Key Id (username) and Secret Key (password).
+
+To use temporary session credentials (e.g. for an AWS IAM Role), add the `X-Amz-Security-Token` header containing the session token.

docs/spec/cmdline-opts-hurl/cacert_file.option

@@ -0,0 +1,9 @@
+name: client_cert_file
+long: cert
+short: E
+value: CERTIFICATE[:PASSWORD]
+help: Client certificate file and password
+---
+Client certificate file and password.
+
+See also [`--key`](#key).

docs/spec/cmdline-opts-hurl/client_cert_file.option

@@ -0,0 +1,7 @@
+name: cacert_file
+long: cacert
+value: FILE
+help: CA certificate to verify peer against (PEM format)
+---
+Specifies the certificate file for peer verification. The file may contain multiple CA certificates and must be in PEM format.
+Normally Hurl is built to use a default file for this, so this option is typically used to alter that default file.

docs/spec/cmdline-opts-hurl/client_key_file.option

@@ -0,0 +1,6 @@
+name: client_key_file
+long: key
+value: KEY
+help: Private key file name
+---
+Private key file name.

docs/spec/cmdline-opts-hurl/color.option

@@ -0,0 +1,6 @@
+name: color
+long: color
+help: Colorize output
+conflict: no_color
+---
+Colorize debug output (the HTTP response output is not colorized).

docs/spec/cmdline-opts-hurl/compressed.option

@@ -0,0 +1,5 @@
+name: compressed
+long: compressed
+help: Request compressed response (using deflate or gzip)
+---
+Request a compressed response using one of the algorithms br, gzip, deflate and automatically decompress the content.

docs/spec/cmdline-opts-hurl/connect_timeout.option

@@ -0,0 +1,10 @@
+name: connect_timeout
+long: connect-timeout
+value: SECONDS
+value_default: 300
+value_parser: value_parser!(u64)
+help: Maximum time allowed for connection
+---
+Maximum time in seconds that you allow Hurl's connection to take.
+
+See also [`-m, --max-time`](#max-time).

docs/spec/cmdline-opts-hurl/connect_to.option

@@ -0,0 +1,9 @@
+name: connect_to
+long: connect-to
+value: HOST1:PORT1:HOST2:PORT2
+help: For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead
+multi: append
+---
+For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead. This option can be used several times in a command line.
+
+See also [`--resolve`](#resolve).

docs/spec/cmdline-opts-hurl/continue_on_error.option

@@ -0,0 +1,10 @@
+name: continue_on_error
+long: continue-on-error
+help: Continue executing requests even if an error occurs
+---
+Continue executing requests to the end of the Hurl file even when an assert error occurs.
+By default, Hurl exits after an assert error in the HTTP response.
+
+Note that this option does not affect the behavior with multiple input Hurl files.
+
+All the input files are executed independently. The result of one file does not affect the execution of the other Hurl files.

docs/spec/cmdline-opts-hurl/cookies_input_file.option

@@ -0,0 +1,9 @@
+name: cookies_input_file
+long: cookie
+short: b
+value: FILE
+help: Read cookies from FILE
+---
+Read cookies from FILE (using the Netscape cookie file format).
+
+Combined with [`-c, --cookie-jar`](#cookie-jar), you can simulate a cookie storage between successive Hurl runs.

docs/spec/cmdline-opts-hurl/cookies_output_file.option

@@ -0,0 +1,10 @@
+name: cookies_output_file
+long: cookie-jar
+short: c
+value: FILE
+help: Write cookies to FILE after running the session (only for one session)
+---
+Write cookies to FILE after running the session (only for one session).
+The file will be written using the Netscape cookie file format.
+
+Combined with [`-b, --cookie`](#cookie), you can simulate a cookie storage between successive Hurl runs.

docs/spec/cmdline-opts-hurl/delay.option

@@ -0,0 +1,8 @@
+name: delay
+long: delay
+value: MILLISECONDS
+value_default: 0
+value_parser: value_parser!(u64)
+help: Sets delay before each request.
+---
+Sets delay before each request.

docs/spec/cmdline-opts-hurl/error_format.option

@@ -0,0 +1,8 @@
+name: error_format
+long: error-format
+value: FORMAT
+value_default: short
+value_parser: ["short", "long"]
+help: Control the format of error messages
+---
+Control the format of error message (short by default or long)

docs/spec/cmdline-opts-hurl/fail_at_end.option

@@ -0,0 +1,6 @@
+name: fail_at_end
+long: fail-at-end
+help: Fail at end
+deprecated: true
+---
+

docs/spec/cmdline-opts-hurl/file_root.option

@@ -0,0 +1,7 @@
+name: file_root
+long: file-root
+value: DIR
+help: Set root filesystem to import files [default: current directory]
+---
+Set root file system to import files in Hurl. This is used for both files in multipart form data and request body.
+When this is not explicitly defined, the files are relative to the current directory in which Hurl is running.

docs/spec/cmdline-opts-hurl/follow_location.option

@@ -0,0 +1,6 @@
+name: follow_location
+long: location
+short: L
+help: Follow redirects
+---
+Follow redirect. To limit the amount of redirects to follow use the [`--max-redirs`](#max-redirs) option

docs/spec/cmdline-opts-hurl/glob.option

@@ -0,0 +1,10 @@
+name: glob
+long: glob
+value: GLOB
+help: Specify input files that match the given GLOB. Multiple glob flags may be used
+multi: append
+---
+Specify input files that match the given glob pattern.
+
+Multiple glob flags may be used. This flag supports common Unix glob patterns like *, ? and [].
+However, to avoid your shell accidentally expanding glob patterns before Hurl handles them, you must use single quotes or double quotes around each pattern.

docs/spec/cmdline-opts-hurl/http10.option

@@ -0,0 +1,6 @@
+name: http10
+long: http1.0
+short: 0
+help: Tell Hurl to use HTTP version 1.0
+---
+Tells Hurl to use HTTP version 1.0 instead of using its internally preferred HTTP version.

docs/spec/cmdline-opts-hurl/http11.option

@@ -0,0 +1,5 @@
+name: http11
+long: http1.1
+help: Tell Hurl to use HTTP version 1.1
+---
+Tells Hurl to use HTTP version 1.1.

docs/spec/cmdline-opts-hurl/http2.option

@@ -0,0 +1,7 @@
+name: http2
+long: http2
+help: Tell Hurl to use HTTP version 2
+---
+Tells Hurl to use HTTP version 2.
+For HTTPS, this means Hurl negotiates HTTP/2 in the TLS handshake. Hurl does this by default.
+For HTTP, this means Hurl attempts to upgrade the request to HTTP/2 using the Upgrade: request header.

docs/spec/cmdline-opts-hurl/http3.option

@@ -0,0 +1,5 @@
+name: http3
+long: http3
+help: Tell Hurl to use HTTP version 3
+---
+Tells Hurl to try HTTP/3 to the host in the URL, but fallback to earlier HTTP versions if the HTTP/3 connection establishment fails. HTTP/3 is only available for HTTPS and not for HTTP URLs.

docs/spec/cmdline-opts-hurl/ignore_asserts.option

@@ -0,0 +1,5 @@
+name: ignore_asserts
+long: ignore-asserts
+help: Ignore asserts defined in the Hurl file
+---
+Ignore all asserts defined in the Hurl file.

docs/spec/cmdline-opts-hurl/include.option

@@ -0,0 +1,6 @@
+name: include
+long: include
+short: i
+help: Include the HTTP headers in the output
+---
+Include the HTTP headers in the output

docs/spec/cmdline-opts-hurl/insecure.option

@@ -0,0 +1,6 @@
+name: insecure
+long: insecure
+short: k
+help: Allow insecure SSL connections
+---
+This option explicitly allows Hurl to perform "insecure" SSL connections and transfers.

docs/spec/cmdline-opts-hurl/interactive.option

@@ -0,0 +1,8 @@
+name: interactive
+long: interactive
+help: Turn on interactive mode
+conflict: to_entry
+---
+Stop between requests.
+
+This is similar to a break point, You can then continue (Press C) or quit (Press Q).

docs/spec/cmdline-opts-hurl/ipv4.option

@@ -0,0 +1,6 @@
+name: ipv4
+long: ipv4
+short: 4
+help: Tell Hurl to use IPv4 addresses only when resolving host names, and not for example try IPv6
+---
+This option tells Hurl to use IPv4 addresses only when resolving host names, and not for example try IPv6.

docs/spec/cmdline-opts-hurl/ipv6.option

@@ -0,0 +1,6 @@
+name: ipv6
+long: ipv6
+short: 6
+help: Tell Hurl to use IPv6 addresses only when resolving host names, and not for example try IPv4
+---
+This option tells Hurl to use IPv6 addresses only when resolving host names, and not for example try IPv4.

docs/spec/cmdline-opts-hurl/json.option

@@ -0,0 +1,6 @@
+name: json
+long: json
+help: Output each Hurl file result to JSON
+conflict: no_output
+---
+Output each hurl file result to JSON. The format is very closed to HAR format.

docs/spec/cmdline-opts-hurl/max_redirects.option

@@ -0,0 +1,10 @@
+name: max_redirects
+long: max-redirs
+value: NUM
+value_default: 50
+value_parser: value_parser!(i32).range(-1..)
+help: Maximum number of redirects allowed, -1 for unlimited redirects
+---
+Set maximum number of redirection-followings allowed
+
+By default, the limit is set to 50 redirections. Set this option to -1 to make it unlimited.

docs/spec/cmdline-opts-hurl/max_time.option

@@ -0,0 +1,11 @@
+name: max_time
+long: max-time
+short: m
+value: SECONDS
+value_default: 300
+value_parser: value_parser!(u64)
+help: Maximum time allowed for the transfer
+---
+Maximum time in seconds that you allow a request/response to take. This is the standard timeout.
+
+See also [`--connect-timeout`](#connect-timeout).

docs/spec/cmdline-opts-hurl/no_color.option

@@ -0,0 +1,6 @@
+name: no_color
+long: no-color
+help: Do not colorize output
+conflict: color
+---
+Do not colorize output.

docs/spec/cmdline-opts-hurl/no_output.option

@@ -0,0 +1,6 @@
+name: no_output
+long: no-output
+help: Suppress output. By default, Hurl outputs the body of the last response
+conflict: json
+---
+Suppress output. By default, Hurl outputs the body of the last response.

docs/spec/cmdline-opts-hurl/noproxy.option

@@ -0,0 +1,8 @@
+name: noproxy
+long: noproxy
+value: HOST(S)
+help: List of hosts which do not use proxy
+---
+Comma-separated list of hosts which do not use a proxy.
+
+Override value from Environment variable no_proxy.

docs/spec/cmdline-opts-hurl/output.option

@@ -0,0 +1,7 @@
+name: output
+long: output
+short: o
+value: FILE
+help: Write to FILE instead of stdout
+---
+Write output to FILE instead of stdout.

docs/spec/cmdline-opts-hurl/path_as_is.option

@@ -0,0 +1,5 @@
+name: path_as_is
+long: path-as-is
+help: Tell Hurl to not handle sequences of /../ or /./ in the given URL path
+---
+Tell Hurl to not handle sequences of /../ or /./ in the given URL path. Normally Hurl will squash or merge them according to standards but with this option set you tell it not to do that.

docs/spec/cmdline-opts-hurl/proxy.option

@@ -0,0 +1,7 @@
+name: proxy
+long: proxy
+short: x
+value: [PROTOCOL://]HOST[:PORT]
+help: Use proxy on given PROTOCOL/HOST/PORT
+---
+Use the specified proxy.

docs/spec/cmdline-opts-hurl/report_html.option

@@ -0,0 +1,8 @@
+name: report_html
+long: report-html
+value: DIR
+help: Generate HTML report to DIR
+---
+Generate HTML report in DIR.
+
+If the HTML report already exists, it will be updated with the new test results.

docs/spec/cmdline-opts-hurl/report_junit.option

@@ -0,0 +1,8 @@
+name: report_junit
+long: report-junit
+value: FILE
+help: Write a JUnit XML report to FILE
+---
+Generate JUnit File.
+
+If the FILE report already exists, it will be updated with the new test results.

docs/spec/cmdline-opts-hurl/report_tap.option

@@ -0,0 +1,8 @@
+name: report_tap
+long: report-tap
+value: FILE
+help: Write a TAP report to FILE
+---
+Generate TAP report.
+
+If the FILE report already exists, it will be updated with the new test results.

docs/spec/cmdline-opts-hurl/resolve.option

@@ -0,0 +1,7 @@
+name: resolve
+long: resolve
+value: HOST:PORT:ADDR
+help: Provide a custom address for a specific HOST and PORT pair
+multi: append
+---
+Provide a custom address for a specific host and port pair. Using this, you can make the Hurl requests(s) use a specified address and prevent the otherwise normally resolved address to be used. Consider it a sort of /etc/hosts alternative provided on the command line.

docs/spec/cmdline-opts-hurl/retry.option

@@ -0,0 +1,8 @@
+name: retry
+long: retry
+value: NUM
+value_default: 0
+value_parser: value_parser!(i32).range(-1..)
+help: Maximum number of retries, 0 for no retries, -1 for unlimited retries
+---
+Maximum number of retries, 0 for no retries, -1 for unlimited retries. Retry happens if any error occurs (asserts, captures, runtimes etc...).

docs/spec/cmdline-opts-hurl/retry_interval.option

@@ -0,0 +1,8 @@
+name: retry_interval
+long: retry-interval
+value: MILLISECONDS
+value_default: 1000
+value_parser: value_parser!(u64)
+help: Interval in milliseconds before a retry
+---
+Duration in milliseconds between each retry. Default is 1000 ms.

docs/spec/cmdline-opts-hurl/ssl_no_revoke.option

@@ -0,0 +1,5 @@
+name: ssl_no_revoke
+long: ssl-no-revoke
+help: (Windows) Tell Hurl to disable certificate revocation checks. WARNING: this option loosens the SSL security, and by using this flag you ask for exactly that.
+---
+(Windows) This option tells Hurl to disable certificate revocation checks. WARNING: this option loosens the SSL security, and by using this flag you ask for exactly that.

docs/spec/cmdline-opts-hurl/test.option

@@ -0,0 +1,5 @@
+name: test
+long: test
+help: Activate test mode
+---
+Activate test mode: with this, the HTTP response is not outputted anymore, progress is reported for each Hurl file tested, and a text summary is displayed when all files have been run.

docs/spec/cmdline-opts-hurl/to_entry.option

@@ -0,0 +1,9 @@
+name: to_entry
+long: to-entry
+value: ENTRY_NUMBER
+value_parser: value_parser!(u32).range(1..)
+help: Execute Hurl file to ENTRY_NUMBER (starting at 1)
+conflict: interactive
+---
+Execute Hurl file to ENTRY_NUMBER (starting at 1).
+Ignore the remaining of the file. It is useful for debugging a session.

docs/spec/cmdline-opts-hurl/user.option

@@ -0,0 +1,7 @@
+name: user
+long: user
+short: u
+value: USER:PASSWORD
+help: Add basic Authentication header to each request
+---
+Add basic Authentication header to each request.

docs/spec/cmdline-opts-hurl/user_agent.option

@@ -0,0 +1,7 @@
+name: user_agent
+long: user-agent
+short: A
+value: NAME
+help: Specify the User-Agent string to send to the HTTP server
+---
+Specify the User-Agent string to send to the HTTP server.

docs/spec/cmdline-opts-hurl/variable.option

@@ -0,0 +1,7 @@
+name: variable
+long: variable
+value: NAME=VALUE
+help: Define a variable
+multi: append
+---
+Define variable (name/value) to be used in Hurl templates.

docs/spec/cmdline-opts-hurl/variables_file.option

@@ -0,0 +1,11 @@
+name: variables_file
+long: variables-file
+value: FILE
+help: Define a properties file in which you define your variables
+multi: append
+---
+Set properties file in which your define your variables.
+
+Each variable is defined as name=value exactly as with [`--variable`](#variable) option.
+
+Note that defining a variable twice produces an error.

docs/spec/cmdline-opts-hurl/verbose.option

@@ -0,0 +1,12 @@
+name: verbose
+long: verbose
+help: Turn on verbose
+---
+Turn on verbose output on standard error stream.
+Useful for debugging.
+
+A line starting with '>' means data sent by Hurl.
+A line staring with '<' means data received by Hurl.
+A line starting with '*' means additional info provided by Hurl.
+
+If you only want HTTP headers in the output, [`-i, --include`](#include) might be the option you're looking for.

docs/spec/cmdline-opts-hurl/very_verbose.option

@@ -0,0 +1,7 @@
+name: very_verbose
+long: very-verbose
+help: Turn on verbose output, including HTTP response and libcurl logs
+---
+Turn on more verbose output on standard error stream.
+
+In contrast to  [`--verbose`](#verbose) option, this option outputs the full HTTP body request and response on standard error. In addition, lines starting with '**' are libcurl debug logs.