From 0e39ff753502e3e1a26d75d74e8434c32c8cdad2 Mon Sep 17 00:00:00 2001 From: matosys Date: Mon, 13 Apr 2026 15:10:35 +0200 Subject: [PATCH] docs(*): add basic documentation for project --- docs/source/examples.rst | 41 ++++++- docs/source/features.rst | 38 ++++-- docs/source/topic_intro.rst | 237 +++++++++++++++++++++++++++++++++++- docs/source/utilities.rst | 21 +++- 4 files changed, 321 insertions(+), 16 deletions(-) diff --git a/docs/source/examples.rst b/docs/source/examples.rst index 198f2d7..84b8074 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -1,4 +1,43 @@ Examples ******** -.. todo provide some examples \ No newline at end of file +This package provides a feature to interact by a session-based web session. It also provides a ready-to-use +implementation with :class:`balderhub.http.lib.setup_features.client.WebSessionWithRequestsFeature` using the +`python requests package `_. + +Creating universal Scenarios +============================ + +If you need a web session within a test scenario, you can use the +:class:`balderhub.http.lib.scenario_features.client.WebSessionFeature` like shown below: + +.. code-block:: python + + from balderhub.http.lib.utils import HttpMethod + + class ScenarioExample(balder.Scenario): + + class WebSessionDevice(balder.Device): + web = balderhub.http.lib.scenario_features.client.WebSessionFeature() + ... + + def test_check_website(self): + response = self.WebSessionDevice.web.request(HttpMethod.GET, "https://docs.balder.dev") + assert response.status_code == 200, response + +Using it in Setups +================== + +You can use a ready-to-use implementation for the :class:`balderhub.http.lib.scenario_features.client.WebSessionFeature` +with the shipped :class:`balderhub.http.lib.setup_features.client.WebSessionWithRequestsFeature`: + + +.. code-block:: python + + from balderhub.http.lib.utils import HttpMethod + + class SetupWithRequests(balder.Scenario): + + class Client(balder.Device): + web = balderhub.http.lib.setup_features.client.WebSessionWithRequestsFeature() + ... diff --git a/docs/source/features.rst b/docs/source/features.rst index 06d6da1..528dc87 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -8,20 +8,40 @@ This section describes all features that are shipped with this package. Scenario Features ================= -.. note:: - This package does not provide any scenario features +Client Scenario Features +------------------------ + +.. autoclass:: balderhub.http.lib.scenario_features.client.WebSessionFeature + :members: + +Server Scenario Features +------------------------ -.. todo add your features with .. autoclass - .. autoclass:: balderhub.http.lib.scenario_features.MyScenarioFeature - :members: + +.. note:: + This package does not provide any server scenario features yet. Setup Features ============== +Client Setup Features +--------------------- + +The following section holds client setup features that provides implementation for clients like browsers or command +line tools. + +.. todo + +.. autoclass:: balderhub.http.lib.setup_features.client.WebSessionWithRequestsFeature + :members: + +Server Setup Features +--------------------- + +This section holds server setup features that provides implementation for http servers or further developed servers +that are using the http protocol. + .. note:: - This package does not provide any setup features. + This package does not provide any server setup features yet. -.. todo add your features with .. autoclass - .. autoclass:: balderhub.http.lib.setup_features.MySetupFeature - :members: \ No newline at end of file diff --git a/docs/source/topic_intro.rst b/docs/source/topic_intro.rst index e33fc19..5518526 100644 --- a/docs/source/topic_intro.rst +++ b/docs/source/topic_intro.rst @@ -1,4 +1,239 @@ Introduction into HTTP ********************** -.. todo provide an explanation of your specific topic that can help others to use your BalderHub project \ No newline at end of file +.. note:: + This section is still under development. If you would like to contribute, feel free to + `open a Pull Request `_. + +HTTP is a stateless protocol for web communication, likely operating on a request-response model. + +Resources are identified by URIs, with methods like GET and POST defining actions. + +The evidence leans toward HTTP having versions like 1.1, 2, and 3, each with performance enhancements. + +This BalderHub package should following RFC's: + +* `RFC 9110: HTTP Semantics `_ +* `RFC 9112: HTTP/1.1 `_ + +Overview +======== + +HTTP, or Hypertext Transfer Protocol, is the backbone of web communication, enabling data exchange between clients +(like browsers) and servers. It operates on a stateless, request-response model, meaning each request is independent, +and the server responds to each without retaining prior interaction details. + +How HTTP Works +-------------- + +In HTTP, a client sends a request to a server, specifying: + +**Method:** The action, such as GET to retrieve data or POST to submit it. + +**URI:** Identifies the resource, like a webpage or file. + +**Headers:** Provide additional information, like content type or language preferences. + +The server processes this and returns a response with: + +**Status Code:** Indicates success (e.g., 200 OK) or failure (e.g., 404 Not Found). + +**Headers:** Metadata about the response. + +**Body:** The actual data, like HTML content or an image. + +Versions and Features +--------------------- + +HTTP has evolved, with versions like: + +**HTTP/1.1:** Introduced persistent connections for efficiency. + +**HTTP/2:** Added multiplexing and header compression for faster performance. + +**HTTP/3:** Uses QUIC for reduced latency, enhancing reliability. + +It also supports content negotiation, allowing clients and servers to agree on data formats, and caching to store +responses for reuse, improving speed and reducing server load. For secure communication, HTTP can use TLS, known as +HTTPS, encrypting data to protect against eavesdropping. + +For detailed specifications, refer to the official RFC documents: + +* `RFC 9110: HTTP Semantics `_ +* `RFC 9112: HTTP/1.1 `_ +* `RFC 9113: HTTP/2 `_ +* `RFC 9114: HTTP/3 `_ + +Comprehensive Analysis of HTTP Operations +========================================= + +This section provides an in-depth exploration of the Hypertext Transfer Protocol (HTTP), detailing its mechanisms, +evolution, and technical specifications, particularly referencing the relevant Request for Comments (RFC) documents. + +Introduction to HTTP +-------------------- + +HTTP, first specified in the early 1990s, is a stateless, application-level protocol designed for distributed, +collaborative, hypertext information systems. As outlined in +`RFC 9110: HTTP Semantics `_, it is a family of request/response protocols +sharing a generic interface, extensible semantics, and self-descriptive messages. This design enables flexible +interaction, hiding implementation details and presenting a uniform interface to clients, independent of resource types. +The protocol's focus on communication syntax, intent, and expected recipient behavior, as noted in the introduction, +emphasizes observable interface changes, supporting intermediation through proxies and gateways for translating +non-HTTP systems. + +Core Operational Mechanisms +--------------------------- + +HTTP operates on a request-response model, where clients initiate communication by sending HTTP requests to servers, +which respond accordingly. + +The key components, detailed in `RFC 9110 `_, include: + +**Resources and URIs:** Resources, the targets of HTTP requests, are identified by Uniform Resource Identifiers (URIs), +as per Section 3.1 of RFC 9110. This identification allows precise location and access, crucial for web navigation. + +**Methods:** + +HTTP defines a set of request methods indicating the desired action on a resource. Common methods, as referenced in +RFC 9110, include: + +* ``GET:`` Retrieve a representation (Section 9.3.1). + +* ``POST:`` Submit data for processing (Section 9.3.3). + +* ``PUT:`` Update with provided representation (Section 9.3.4). + +* ``DELETE:`` Remove the resource (Section 9.3.5). + +* ``HEAD:`` Retrieve headers only (Section 9.3.2). + +* ``OPTIONS:`` Retrieve communication options (Section 9.3.7). + +These methods are part of the core semantics, ensuring a uniform interface as described in Section 1.3 of RFC 9110. + +**Headers and Metadata:** + +Headers, detailed in Section 6.3 of RFC 9110, are key-value pairs providing metadata about the request or response. +They include information like content type (Content-Type), length (Content-Length), and caching directives +(Cache-Control). New field values must follow ABNF from `RFC 9110 `__ or +`RFC 8941 `__: Structured Field Values for HTTP, ensuring compatibility and +extensibility. + +**Status Codes:** + +Responses include three-digit status codes, as outlined in +`Section 15 of RFC 9110 `_, indicating the request's outcome. + +Examples include: + +* ``200 OK``: Successful request. + +* ``404 Not Found``: Resource unavailable. + +* ``500 Internal Server Error``: Server-side issue. + +These codes, along with optional reason phrases, form the start line of responses, as per Section 6.2. + +**Message Body and Representations:** + +The message body, as described in `Section 6.4 of RFC 9110 `_, +contains the representation data, such as HTML, images, or JSON, reflecting the resource's state. Representations are +central to HTTP's uniform interface, enabling content negotiation, detailed in +`Section 12 of RFC 9110 `_, where clients and servers +agree on format and language via headers like Accept and Accept-Language. + +**Message Format:** + +HTTP messages, as per `Section 3.4 of RFC 9110 `_ and +`Section 6 of RFC 9110 `_, consist of a start line, +headers, an optional body, and trailers. For requests, the start line includes the method, request target, and HTTP +version; for responses, it includes the version, status code, and reason phrase. The format supports framing, with +modern versions using length-delimited sequences, as noted in +`Section 6.1 of RFC 9110 `_, moving away from +connection closure in early versions like ``HTTP/0.9``. + +Evolution and Versions +---------------------- + +HTTP has evolved significantly since its inception, with versions enhancing performance and functionality. The history, +as outlined in `Section 1.2 of RFC 9110 `_, shows: + +**HTTP/1.1:** + +Defined in `RFC 9112: HTTP/1.1 `_, it introduced persistent connections, +chunked transfer encoding, and refined caching mechanisms, standardizing features from 1995 and revised in 2014. + +**HTTP/2:** + +Specified in `RFC 9113: HTTP/2 `_, it added multiplexing for concurrent +requests, header compression using HPACK (RFC 7541), and server push, improving efficiency over TCP and TLS. + +**HTTP/3:** + +Detailed in `RFC 9114: HTTP/3 `_, it uses the QUIC transport protocol over UDP, +offering stream multiplexing, per-stream flow control, and low-latency connection establishment, enhancing performance +and reliability. + + +All versions share core semantics from `RFC 9110 `_, with separate documents +for caching (`RFC 9111 `_) and specific version syntax, allowing independent +progression as noted in the history section. + +Additional Features and Security +-------------------------------- + +HTTP includes mechanisms for caching, as per `RFC 9111 `_, controlled by +headers like Cache-Control, ETag, and Last-Modified, enabling clients and intermediaries to store responses, reducing +latency and server load. Content negotiation, as mentioned, enhances flexibility, while security is addressed through +HTTPS, HTTP over TLS, as referenced in RFCs like `RFC 5246: TLS 1.2 `_ and +`RFC 8446: TLS 1.3 `_, encrypting data to protect against eavesdropping and +tampering. + +Comprehensive Table of RFC Specifications +----------------------------------------- + +Below is a table summarizing the key RFCs relevant to HTTP, ensuring a complete reference for documentation: + + ++-------------------------------------------------------+----------------+------------------------------------+------------+ +| RFC | Title | Description | Status | ++=======================================================+================+====================================+============+ +| `RFC 9110 `_ | HTTP Semantics | Defines core protocol elements, | Internet | +| | | extensibility, and URI schemes, | Standard | +| | | obsoleting RFCs 2818, 7231, etc. | | ++-------------------------------------------------------+----------------+------------------------------------+------------+ +| `RFC 9111 `_ | HTTP Caching | Details caching mechanisms, | Internet | +| | | enhancing efficiency. | Standard | +| | | | | ++-------------------------------------------------------+----------------+------------------------------------+------------+ +| `RFC 9112 `_ | HTTP/1.1 | Specifies message syntax, parsing, | Internet | +| | | and connection management for | Standard | +| | | HTTP/1.1. | | ++-------------------------------------------------------+----------------+------------------------------------+------------+ +| `RFC 9113 `_ | HTTP/2 | Describes optimized semantics with | Proposed | +| | | multiplexing and compression, | Standard | +| | | obsoleting RFC 7540. | | ++-------------------------------------------------------+----------------+------------------------------------+------------+ +| `RFC 9114 `_ | HTTP/3 | Maps HTTP semantics over QUIC, | Proposed | +| | | enhancing performance with low | Standard | +| | | latency. | | ++-------------------------------------------------------+----------------+------------------------------------+------------+ +| `RFC 8941 `_ | Structured | Defines field value syntax for | Proposed | +| | Field Values | headers, used in RFC 9110. | Standard | +| | for HTTP | | | ++-------------------------------------------------------+----------------+------------------------------------+------------+ +| `RFC 7541 `_ | HPACK: Header | Details header compression for | Standards | +| | Compression | HTTP/2, enhancing efficiency. | Track | +| | for HTTP/2 | | | ++-------------------------------------------------------+----------------+------------------------------------+------------+ +| `RFC 5246 `_ | TLS Protocol | Supports secure HTTP via TLS, | Proposed | +| | Version 1.2 | referenced for HTTPS. | Standard | ++-------------------------------------------------------+----------------+------------------------------------+------------+ +| `RFC 8446 `_ | TLS Protocol | Latest TLS version, enhancing | Proposed | +| | Version 1.3 | HTTPS security. | Standard | ++-------------------------------------------------------+----------------+------------------------------------+------------+ + + +The goal of this project is providing test features and support objects to be compatible with the mentioned RFCs. + diff --git a/docs/source/utilities.rst b/docs/source/utilities.rst index 12bdf05..c2515f7 100644 --- a/docs/source/utilities.rst +++ b/docs/source/utilities.rst @@ -4,10 +4,21 @@ Utilities This section shows general objects and helper functions that are used with this package. -.. note:: - This BalderHub project doesn't have any utilities. +.. autoclass:: balderhub.http.lib.utils.HttpRequestMessage + :members: + +.. autoclass:: balderhub.http.lib.utils.Response + :members: + +Enums +===== + +.. autoclass:: balderhub.http.lib.utils.HttpMethod + :members: + +Further functions +================= + +.. autofunction:: balderhub.http.lib.utils.functions.convert_requests_response -.. todo add your scenarios with .. autoclass - .. autoclass:: balderhub.http.lib.utilities.MyExampleUtility - :members: