add comments to guide future developers

Author: Ahmed TAHRI

docs/README.md

@@ -1530,13 +1530,13 @@ $ http --cert=client.pem --cert-key=client.key --cert-key-pass=my_password https
 ### SSL version
 
 Use the `--ssl=<PROTOCOL>` option to specify the desired protocol version to use.
-This will default to SSL v2.3 which will negotiate the highest protocol that both the server and your installation of OpenSSL support.
-The available protocols are `ssl2.3`, `ssl3`, `tls1`, `tls1.1`, `tls1.2`, `tls1.3`.
+This will default to TLS v1.0 which will negotiate the highest protocol that both the server and your installation of OpenSSL support.
+The available protocols are `tls1`, `tls1.1`, `tls1.2`, `tls1.3`.
 (The actually available set of protocols may vary depending on your OpenSSL installation.)
 
 ```bash
-# Specify the vulnerable SSL v3 protocol to talk to an outdated server:
-$ http --ssl=ssl3 https://vulnerable.example.org
+# Specify the vulnerable TLS 1 protocol to talk to an outdated server:
+$ http --ssl=tls1 https://vulnerable.example.org
 ```
 
 ### SSL ciphers

httpie/cli/argparser.py

@@ -175,7 +175,8 @@ def parse_args(
         self._process_pretty_options()
         self._process_format_options()
 
-        # bellow is a fix for detecting "false-or empty" stdin
+        # bellow is a fix for detecting "false-or empty" stdin.
+        # see https://github.com/httpie/cli/issues/1551 for more information.
         if self.has_stdin_data:
             read_event = threading.Event()
             observe_stdin_for_data_thread(env, self.env.stdin, read_event)

httpie/client.py

@@ -8,6 +8,8 @@
 from urllib.parse import urlparse, urlunparse
 
 import niquests
+# to understand why this is required
+# see https://niquests.readthedocs.io/en/latest/community/faq.html#what-is-urllib3-future
 from niquests._compat import HAS_LEGACY_URLLIB3
 
 if not HAS_LEGACY_URLLIB3:
@@ -120,6 +122,10 @@ def collect_messages(
 
     hooks = None
 
+    # The hook set up bellow is crucial for HTTPie.
+    # It will help us yield the request before it is
+    # actually sent. This will permit us to know about
+    # the connection information for example.
     if prepared_request_readiness:
         hooks = {"pre_send": [prepared_request_readiness]}
 

httpie/core.py

@@ -206,6 +206,8 @@ def request_body_read_callback(chunk: bytes):
             downloader.pre_request(args.headers)
 
         def prepared_request_readiness(pr):
+            """This callback is meant to output the request part. It is triggered by
+            the underlying Niquests library just after establishing the connection."""
 
             oo = OutputOptions.from_message(
                 pr,
@@ -252,7 +254,11 @@ def prepared_request_readiness(pr):
                     is_streamed_upload = not isinstance(message.body, (str, bytes))
                     do_write_body = not is_streamed_upload
                     force_separator = is_streamed_upload and env.stdout_isatty
+                # We're in a REQUEST message, we rather output the message
+                # in prepared_request_readiness because we want "message.conn_info"
+                # to be set appropriately. (e.g. know about HTTP protocol version, etc...)
                 if message.conn_info is None and not args.offline:
+                    # bellow variable will be accessed by prepared_request_readiness just after.
                     prev_with_body = output_options.body
                     continue
             else:

httpie/internal/encoder.py

@@ -21,6 +21,8 @@
 import os
 from uuid import uuid4
 
+# to understand why this is required
+# see https://niquests.readthedocs.io/en/latest/community/faq.html#what-is-urllib3-future
 from niquests._compat import HAS_LEGACY_URLLIB3
 
 if HAS_LEGACY_URLLIB3:

httpie/models.py

@@ -2,6 +2,8 @@
 
 import niquests
 
+# to understand why this is required
+# see https://niquests.readthedocs.io/en/latest/community/faq.html#what-is-urllib3-future
 from niquests._compat import HAS_LEGACY_URLLIB3
 
 if not HAS_LEGACY_URLLIB3:
@@ -109,6 +111,8 @@ def metadata(self) -> str:
         time_since_headers_parsed = monotonic() - self._orig._httpie_headers_parsed_at
         time_elapsed = time_to_parse_headers + time_since_headers_parsed
 
+        # metrics aren't guaranteed to be there. act with caution.
+        # see https://niquests.readthedocs.io/en/latest/user/advanced.html#event-hooks for more.
         if hasattr(self._orig, "conn_info") and self._orig.conn_info:
             if self._orig.conn_info.resolution_latency:
                 data[ELAPSED_DNS_RESOLUTION_LABEL] = str(round(self._orig.conn_info.resolution_latency.total_seconds(), 10)) + 's'

httpie/output/streams.py

@@ -91,7 +91,7 @@ def __iter__(self) -> Iterable[bytes]:
 class RawStream(BaseStream):
     """The message is streamed in chunks with no processing."""
 
-    CHUNK_SIZE = -1
+    CHUNK_SIZE = -1  # '-1' means that we want to receive chunks exactly as they arrive.
     CHUNK_SIZE_BY_LINE = 1
 
     def __init__(self, chunk_size=CHUNK_SIZE, **kwargs):

httpie/ssl_.py

@@ -12,11 +12,17 @@
     resolve_ssl_version,
 )
 
-
+# the minimum one may hope to negotiate with Python 3.7+ is tls1+
+# anything else would be unsupported.
 SSL_VERSION_ARG_MAPPING = {
+    'tls1': 'PROTOCOL_TLSv1',
+    'tls1.1': 'PROTOCOL_TLSv1_1',
     'tls1.2': 'PROTOCOL_TLSv1_2',
     'tls1.3': 'PROTOCOL_TLSv1_3',
 }
+# todo: we'll need to update this in preparation for Python 3.13+
+# could be a removal (after a long deprecation about constants
+# PROTOCOL_TLSv1, PROTOCOL_TLSv1_1, ...).
 AVAILABLE_SSL_VERSION_ARG_MAPPING = {
     arg: getattr(ssl, constant_name)
     for arg, constant_name in SSL_VERSION_ARG_MAPPING.items()
@@ -27,6 +33,9 @@
 class QuicCapabilityCache(
     MutableMapping[Tuple[str, int], Optional[Tuple[str, int]]]
 ):
+    """This class will help us keep (persistent across runs) what hosts are QUIC capable.
+    See https://urllib3future.readthedocs.io/en/latest/advanced-usage.html#remembering-http-3-over-quic-support for
+    the implementation guide."""
 
     def __init__(self):
         self._cache = {}
@@ -77,6 +86,7 @@ def to_raw_cert(self):
         """Synthesize a requests-compatible (2-item tuple of cert and key file)
         object from HTTPie's internal representation of a certificate."""
         if self.key_password:
+            # Niquests support 3-tuple repr in addition to the 2-tuple repr
             return self.cert_file, self.key_file, self.key_password
         return self.cert_file, self.key_file