Doc: add documentation for APIRequest

mechanical-orchard · Oct 2, 2024 · b248231 · b248231
1 parent 95485d7
commit b248231
Show file tree

Hide file tree

Showing 3 changed files with 465 additions and 430 deletions.
diff --git a/lib/playwright/api_request.ex b/lib/playwright/api_request.ex
@@ -25,29 +25,97 @@ defmodule Playwright.APIRequest do
         }
 
   @typedoc "Options for calls to `new_context/1`"
-  @type options :: map()
-  # %{
-  #   base_url: String.t(),
-  #   extra_http_headers: map(),
-  #   http_credentials: http_credentials(),
-  #   ignore_https_errors: boolean(),
-  #   proxy: proxy_settings(),
-  #   user_agent: String.t(),
-  #   timeout: float(),
-  #   storage_state: storage_state() | String.t() | Path.t(),
-  #   client_certificates: [client_certificate()]
-  # }
+  @type options :: %{
+          optional(:base_url) => String.t(),
+          optional(:client_certificates) => [client_certificate()],
+          optional(:extra_http_headers) => http_headers(),
+          optional(:http_credentials) => http_credentials(),
+          optional(:ignore_https_errors) => boolean(),
+          optional(:proxy) => proxy_settings(),
+          optional(:storage_state) => storage_state() | Path.t() | String.t(),
+          optional(:timeout) => float(),
+          optional(:user_agent) => String.t()
+        }
+
+  @typedoc """
+  A client certificate to be used in requests.
+  """
+  @type client_certificate :: %{
+          required(:origin) => String.t(),
+          optional(:cert_path) => Path.t() | String.t(),
+          optional(:key_path) => Path.t() | String.t(),
+          optional(:pfx_path) => Path.t() | String.t(),
+          optional(:passphrase) => String.t()
+        }
+
+  @typedoc """
+  A `map` containing additional HTTP headers to be sent with every request.
+  """
+  @type http_headers :: %{required(String.t()) => String.t()}
+
+  @typedoc "HTTP authetication credentials."
+  @type http_credentials() :: %{
+          required(:username) => String.t(),
+          required(:password) => String.t(),
+          optional(:origin) => String.t(),
+          optional(:send) => :always | :unauthorized
+        }
+
+  @typedoc "Network proxy settings."
+  @type proxy_settings :: %{
+          required(:server) => String.t(),
+          optional(:bypass) => String.t(),
+          optional(:username) => String.t(),
+          optional(:password) => String.t()
+        }
+
+  @typedoc "Storage state settings."
+  @type storage_state :: %{
+          required(:cookies) => [cookie()],
+          required(:origins) => [
+            %{
+              required(:origin) => String.t(),
+              required(:local_storage) => [local_storage()]
+            }
+          ]
+        }
+
+  @typedoc "An HTTP cookie."
+  @type cookie :: %{
+          required(:name) => String.t(),
+          required(:value) => String.t(),
+          required(:domain) => String.t(),
+          required(:path) => String.t(),
+          required(:expires) => float(),
+          required(:http_only) => boolean(),
+          required(:secure) => boolean(),
+          required(:same_site) => :lax | :none | :strict
+        }
+
+  @typedoc "Local storage settings."
+  @type local_storage :: %{
+          required(:name) => String.t(),
+          required(:value) => String.t()
+        }
 
   @doc """
   Returns a new `Playwright.APIRequest`.
 
-  ## Returns
+  See also `Playwright.request/1` which is a more likely entry-point.
 
-    - `Playwright.APIRequest.t()`
+  ## Usage
+
+      request = APIRequest.new(session)
+
+  ## Arguments
 
-  ## Parameters
+  | name      | description                                  |
+  | --------- | -------------------------------------------- |
+  | `session` | The `pid` for the current Playwright session |
+
+  ## Returns
 
-  - session ...
+    - `Playwright.APIRequest.t()`
   """
   @spec new(pid()) :: t()
   def new(session) do
@@ -60,39 +128,34 @@ defmodule Playwright.APIRequest do
   @doc """
   Creates a new instance of `Playwright.APIRequestContext`.
 
-  ## Returns
+  ## Usage
 
-    - `Playwright.APIRequestContext.t()`
-    - `{:error, Playwright.API.Error.t()}`
+      request = Playwright.request(session)
 
-  ## Parameters
+      APIRequest.new_context(request)
+      APIRequest.new_context(request, options)
 
-  - request ...
-  - options
+      APIRequest.new_context!(request)
+      APIRequest.new_context!(request, options)
 
-  ## Options
+  ## Arguments
+
+  | name      |            | description                |
+  | --------- | ---------- | -------------------------- |
+  | `request` |            | The "subject" `APIRequest` |
+  | `options` | (optional) | `APIRequest.options()`     |
 
-  | name                   | type                     |
-  | ---------------------- | ------------------------ |
-  | `:base_url`            | `String.t()`             |
-  | `:extra_http_headers`  | `map()`                  |
-  | `:http_credentials`    | `[http_credential()]`    |
-  | `:ignore_https_errors` | `boolean()`              |
-  | `:proxy`               | `proxy()`                |
-  | `:user_agent`          | `String.t()`             |
-  | `:timeout`             | `float()`                |
-  | `:storage_state`       | `storage_state()`        |
-  | `:client_certififates` | `[client_certificate()]` |
+  ## Options
 
-  ---
+  <div style="text-align: center;">⋯</div>
 
   ### Option: `:base_url`
 
   Functions such as `Playwright.APIRequestContext.get/3` take the base URL into
   consideration by using the [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL)
   constructor for building the corresponding require URL.
 
-  Examples:
+  #### Examples
 
   - With `base_url: http://localhost:3000`, sending a request to `/bar.html`
     results in `http://localhost:3000/bar.html`.
@@ -101,59 +164,82 @@ defmodule Playwright.APIRequest do
   - With `base_url: http://localhost:3000/foo` (without the trailing slash),
     navigating to `./bar.html` results in `http://localhost:3000/bar.html`.
 
-  ---
+  <div style="text-align: center;">⋯</div>
+
+  ### Option: `:client_certificates`
+
+  A list of client certificates to be used. Each certificate instance must have
+  both `:cert_path` and `:key_path` or a single `:pfx_path` to load the client
+  certificate. Optionally, the `:passphrase` property should be provided if the
+  certficiate is encrypted. The `:origin` property should be provided with an
+  exact match to the request origin for which the certificate is valid.
+
+  TLS client authentication allows the server to request a client certificate
+  and verify it.
+
+  > #### NOTE {: .info}
+  >
+  > Using client certificates in combination with proxy servers is not supported.
+
+  > #### NOTE {: .info}
+  >
+  > When using WebKit on macOS, accessing `localhost` will not pick up client
+  > certificates. As a work-around: replace `localhost` with `local.playwright`.
+
+  #### Certificate details
+
+  | name          |            | description                       |
+  | ------------- | ---------- | --------------------------------- |
+  | `:origin`     |            | Exact origin that the certificate is valid for. Origin includes https protocol, a hostname and optionally a port. |
+  | `:cert_path`  | (optional) | Path to the file with the certificate in PEM format. |
+  | `:key_path`   | (optional) | Path to the file with the private key in PEM format. |
+  | `:pfx_path`   | (optional) | Path to the PFX or PKCS12 encoded private key and certificate chain. |
+  | `:passphrase` | (optional) | Passphrase for the private key (PEM or PFX). |
+
+  <div style="text-align: center;">⋯</div>
 
   ### Option: `:extra_http_headers`
 
   A `map` containing additional HTTP headers to be sent with every request.
 
+  <div style="text-align: center;">⋯</div>
+
   ### Option: `:http_credentials`
 
   Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
   If no `:origin` is specified, the `:username` and `:password` are sent to any
   servers upon unauthorized responses.
 
-  | name                   | type                                   |
-  | ---------------------- | -------------------------------------- |
-  | `:username`            | `String.t()`                           |
-  | `:password`            | `String.t()`                           |
-  | `:origin`              | `String.t()` (optional)                |
-  | `:send`                | `"always", "unauthorized"` (optional)  |
+  #### Credential details
+
+  | name        |            | description |
+  | ----------- | ---------- | ----------- |
+  | `:username` |            |             |
+  | `:password` |            |             |
+  | `:origin`   | (optional) | Restrain sending http credentials on specific origin (`scheme://host:port`). |
+  | `:send`     | (optional) | This option only applies to the requests sent from corresponding `APIRequestContext` and does not affect requests sent from the browser. `:always` - `Authorization` header with basic authentication credentials will be sent with the each API request. `:unauthorized`- the credentials are only sent when 401 (Unauthorized) response with `WWW-Authenticate` header is received. Defaults to `:unauthorized`. |
 
-  ---
+  <div style="text-align: center;">⋯</div>
 
   ### Option: `:ignore_https_errors`
 
   Whether to ignore HTTPS errors when sending network requests. Defaults to
   `false`.
 
-  ---
+  <div style="text-align: center;">⋯</div>
 
   ### Option: `:proxy`
 
   Network proxy settings.
 
-  | name        | type                    |
-  | ----------- | ----------------------- |
-  | `:server`   | `String.t()`            |
-  | `:bypass`   | `String.t()` (optional) |
-  | `:username` | `String.t()` (optional) |
-  | `:password` | `String.t()` (optional) |
-
-  ---
-
-  ### Option: `:user_agent`
-
-  Specific user agent to use in this context.
-
-  ---
-
-  ### Option: `:timeout`
-
-  Maximum time in milliseconds to wait for the response. Defaults to `30_000`
-  (30 seconds). Pass `0` to disable the timeout.
+  | name        |            | description |
+  | ----------- | ---------- | ----------- |
+  | `:server`   |            | Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. |
+  | `:bypass`   | (optional) | Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. |
+  | `:username` | (optional) | Optional username to use if HTTP proxy requires authentication. |
+  | `:password` | (optional) | Optional password to use if HTTP proxy requires authentication. |
 
-  ---
+  <div style="text-align: center;">⋯</div>
 
   ### Option: `:storage_state`
 
@@ -164,83 +250,33 @@ defmodule Playwright.APIRequest do
   returned by one of `BrowserContext.storage_state/2` or
   `APIRequestContext.storage_state/2`.
 
-  One of:
+  | name        |            | description |
+  | ----------- | ---------- | ----------- |
+  | `:cookies`  |            | `[APIRequest.cookie()]` |
+  | `:origins`  |            | `[APIRequest.origin()]` |
 
-  - `String.t()`
-  - `Path.t()`
-  - Storage state
+  <div style="text-align: center;">⋯</div>
 
-  Where storage state has the following shape:
-
-  | name        | type      |
-  | ----------- | --------- |
-  | `:cookies`  | **TODO**  |
-  | `:origins`  | **TODO**  |
-
-  ---
-
-  ### Option: `:client_certificates`
-
-  TLS client authentication allows the server to request a client certificate
-  and verify it.
-
-  **Details**
+  ### Option: `:timeout`
 
-  An array of client certificates to be used. Each certificate object must have
-  both `:cert_path` and `:key_path` or a single `:pfx_path` to load the client
-  certificate.
+  Maximum time in milliseconds to wait for the response. Defaults to `30_000`
+  (30 seconds). Pass `0` to disable the timeout.
 
-  Optionally, the `:passphrase` property should be provided if the certficiate
-  is encrypted. The `:origin` property should be provided with an exact match to
-  the request origin for which the certificate is valid.
+  <div style="text-align: center;">⋯</div>
 
-  **NOTES:**
+  ### Option: `:user_agent`
 
-  - Using client certificates in combination with proxy servers is not supported.
-  - When using WebKit on macOS, accessing `localhost` will not pick up client
-    certificates. As a work-around: replace `localhost` with `local.playwright`.
+  Specific user agent to use in this context.
 
-  Where each client certificate has the following shape:
+  ## Returns
 
-  | name          | type                              |
-  | ------------- | --------------------------------- |
-  | `:origin`     | `String.t()`                      |
-  | `:cert_path`  | `Path.t(), String.t()` (optional) |
-  | `:key_path`   | `Path.t(), String.t()` (optional) |
-  | `:pfx_path`   | `Path.t(), String.t()` (optional) |
-  | `:passphrase` | `String.t()` (optional)           |
+    - `Playwright.APIRequestContext.t()`
+    - `{:error, Playwright.API.Error.t()}`
   """
   @pipe {:new_context, [:request]}
   @pipe {:new_context, [:request, :options]}
   @spec new_context(t(), options()) :: t() | {:error, Error.t()}
   def new_context(request, options \\ %{}) do
     Channel.post({request, :new_request}, options)
   end
-
-  # Storage State shape:
-  # {
-  #   cookies: [
-  #     {
-  #       name: str,
-  #       value: str,
-  #       domain: str,
-  #       path: str,
-  #       expires: float,
-  #       httpOnly: bool,
-  #       secure: bool,
-  #       sameSite: Union["Lax", "None", "Strict"]
-  #     }
-  #   ],
-  #   origins: [
-  #     {
-  #       origin: str,
-  #       localStorage: [
-  #         {
-  #           name: str,
-  #           value: str
-  #         }
-  #       ]
-  #     }
-  #   ]
-  # }
 end