Implement new style cookies

2026-04-24 19:53:55 +02:00 · 2022-02-01 12:14:24 +03:00
parent b5623ccc87
commit 65ab7d5caa
27 changed files with 1406 additions and 117 deletions
@@ -2157,6 +2157,85 @@ $ http --session-read-only=./ro-session.json pie.dev/headers Custom-Header:orig-

 ```bash
 $ http --session=./session.json pie.dev/cookies
+```
+
+```json
+{
+    "cookies": {
+        "secret_cookie": "value_1"
+    }
+}
+```
+
+```bash
+$ http --session=./session.json httpbin.org/cookies
+```
+
+```json
+{
+    "cookies": {
+        "secret_cookie": "value_2"
+    }
+}
+```
+
+If you want to make a cookie domain unbound, you can simply set the `domain`
+field to `null` by editing the session file directly:
+
+```json
+{
+    "cookies": [
+        {
+            "domain": null,
+            "expires": null,
+            "name": "generic_cookie",
+            "path": "/",
+            "secure": false,
+            "value": "generic_value"
+        }
+    ]
+}
+```
+
+```bash
+$ http --session=./session.json pie.dev/cookies
+```
+
+```json
+{
+    "cookies": {
+        "generic_cookie": "generic_value"
+    }
+}
+```
+
+### Cookie Storage Behavior
+
+**TL;DR:** Cookie storage priority: Server response > Command line request > Session file
+
+To set a cookie within a Session there are three options:
+
+1. Get a `Set-Cookie` header in a response from a server
+
+   ```bash
+   $ http --session=./session.json pie.dev/cookie/set?foo=bar
+   ```
+
+2. Set the cookie name and value through the command line as seen in [cookies](#cookies)
+
+   ```bash
+   $ http --session=./session.json pie.dev/headers Cookie:foo=bar
+   ```
+
+3. Manually set cookie parameters in the JSON file of the session
+
+   ```json
+   {
+       "__meta__": {
+       "about": "HTTPie session file",
+       "help": "https://httpie.org/doc#sessions",
+       "httpie": "2.2.0-dev"
+       },
       "auth": {
           "password": null,
           "type": null,
@@ -2208,6 +2287,50 @@ Expired cookies are never stored.
 ```

 If you want to upgrade every existing [named session](#named-sessions), you can use `httpie cli sessions upgrade-all` (be aware
+that this won't upgrade [anonymous sessions](#anonymous-sessions)):
+
+```bash
+$ httpie cli sessions upgrade-all
+Refactored 'api_auth' (for 'pie.dev') to the version 3.1.0.
+Refactored 'login_cookies' (for 'httpie.io') to the version 3.1.0.
+```
+
+#### Additional Customizations
+
+| Flag             | Description                                                                                                                                                                                                                  |
+|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--bind-cookies` | Bind all the unbound cookies to the hostname that session belongs. By default, if the cookie is unbound (the `domain` attribute does not exist / set to an empty string) then it will still continue to be a generic cookie. |
+
+These flags can be used to customize the defaults during an `upgrade` operation. They can
+be used in both `sessions upgrade` and `sessions upgrade-all`.
+
+## Config
+
+HTTPie uses a simple `config.json` file.
+The file doesn’t exist by default, but you can create it manually.
+
+### Config file directory
+
+To see the exact location for your installation, run `http --debug` and look for `config_dir` in the output.
+
+The default location of the configuration file on most platforms is `$XDG_CONFIG_HOME/httpie/config.json` (defaulting to `~/.config/httpie/config.json`).
+
+For backwards compatibility, if the directory `~/.httpie` exists, the configuration file there will be used instead.
+
+On Windows, the config file is located at `%APPDATA%\httpie\config.json`.
+
+The config directory can be changed by setting the `$HTTPIE_CONFIG_DIR` environment variable:
+
+```bash
+$ export HTTPIE_CONFIG_DIR=/tmp/httpie
+$ http pie.dev/get
+```
+
+### Configurable options
+
+Currently, HTTPie offers a single configurable option:
+
+#### `default_options`

 An `Array` (by default empty) of default options that should be applied to every invocation of HTTPie.

@@ -2299,6 +2422,23 @@ And since there’s neither data nor `EOF`, it will get stuck. So unless you’r
 change how a response is formatted.

 > Note: Plugins are usually made by our community members, and thus have no direct relationship with
+> the HTTPie project. We do not control / review them at the moment, so use them at your own discretion.
+
+For managing these plugins; starting with 3.0, we are offering a new plugin manager.
+
+This command is currently in beta.
+
+### `httpie plugins`
+
+`plugins` interface is a very simple plugin manager for installing, listing and uninstalling HTTPie plugins.
+
+In the past `pip` was used to install/uninstall plugins, but on some environments (e.g., brew installed
+packages) it wasn’t working properly. The new interface is a very simple overlay on top of `pip` to allow
+plugin installations on every installation method.
+
+By default, the plugins (and their missing dependencies) will be stored under the configuration directory,
+but this can be modified through `plugins_dir` variable on the config.
+
 #### `httpie plugins install`

 For installing plugins from [PyPI](https://pypi.org/) or from local paths, `httpie plugins install`