python/httpie-cli
1
0
Fork 0
mirror of https://github.com/httpie/cli.git synced 2025-08-10 22:42:05 +02:00
Code Activity

Polish sessions docs

Browse Source
This commit is contained in:
Jakub Roztocil
2022-03-07 20:43:48 +01:00
committed by Batuhan Taskaya
parent 395914fb4d
commit 614866eeb2
1 changed files with 69 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
docs/README.md
View File

@@ -2157,30 +2157,28 @@ $ http --session-read-only=./ro-session.json pie.dev/headers Custom-Header:orig-
$ http --session=./session.json pie.dev/cookies
```
```
```json
{
```json
{
"cookies": {
"pie": "apple"
}
}
```
To make a cookie domain _unbound_ (i.e., to make it available to all hosts, including throughout a cross-domain redirect chain), you can set the `domain` field to `null` in the session file:
```bash
$ http --session=./session.json httpbin.org/cookies
```json
{
"cookies": [
{
{
"cookies": {
"domain": null,
"name": "unbound-cookie",
"value": "send-me-to-any-host"
}
]
}
```
If you want to make a cookie domain unbound, you can simply set the `domain`
field to `null` by editing the session file directly:
```bash
$ http --session=./session.json pie.dev/cookies
```
@@ -2189,36 +2187,20 @@ $ http --session=./session.json pie.dev/cookies
{
"cookies": {
"unbound-cookie": "send-me-to-any-host"
"path": "/",
}
}
```
}
```
```bash
$ http --session=./session.json pie.dev/cookies
```
```json
{
"cookies": {
"generic_cookie": "generic_value"
}
}
```
### Cookie storage behavior
There are three possible sources of persisted cookies within a session. They have the following storage priority: 1—response; 2—command line; 3—session file.
1. Receive a response with a `Set-Cookie` header:
```bash
1. Get a `Set-Cookie` header in a response from a server
```bash
$ http --session=./session.json pie.dev/cookie/set?foo=bar
$ http --session=./session.json pie.dev/cookie/set?foo=bar
```
2. Send a cookie specified on the command line as seen in [cookies](#cookies):
@@ -2231,105 +2213,87 @@ $ http --session=./session.json pie.dev/cookies
```json
{
"cookies": {
"__meta__": {
"foo": {
"expires": null,
"path": "/",
"secure": false,
"value": "bar"
"auth": {
}
"type": null,
}
}
},
```
"foo": {
In summary:
"path": "/",
"secure": false,
"value": "bar"
- Cookies set via the CLI overwrite cookies of the same name inside session files.
- Server-sent `Set-Cookie` header cookies overwrite any pre-existing ones with the same name.
Cookie expiration handling:
}
- When the server expires an existing cookie, HTTPie removes it from the session file.
```
Cookies will be set in the session file with the priority specified above.
- When a cookie in a session file expires, HTTPie removes it before sending a new request.
### Upgrading sessions
If the server returns a `Set-Cookie` header with a cookie of the same name, the returned cookie will overwrite the preexisting cookie.
HTTPie may introduce changes in the session file format. When HTTPie detects an obsolete format, it shows a warning. You can upgrade your session files using the following commands:
Expired cookies are never stored.
If a cookie in a session file expires, it will be removed before sending a new request.
If the server expires an existing cookie, it will also be removed from the session file.
### Upgrading Sessions
In rare circumstances, HTTPie makes changes in it's session layout. For allowing a smoother transition of existing files
from the old layout to the new layout we offer 2 interfaces:
- `httpie cli sessions upgrade`
- `httpie cli sessions upgrade-all`
With `httpie cli sessions upgrade`, you can upgrade a single session with it's name (or it's path, if it is an
[anonymous session](#anonymous-sessions)) and the hostname it belongs to. For example:
([named session](#named-sessions))
```bash
$ httpie cli sessions upgrade pie.dev api_auth
Upgrade all existing [named sessions](#named-sessions) inside the `sessions` subfolder of your [config directory](https://httpie.io/docs/cli/config-file-directory):
```bash
$ httpie cli sessions upgrade-all
Upgraded 'api_auth' @ 'pie.dev' to v3.1.0
Upgraded 'login_cookies' @ 'httpie.io' to v3.1.0
```
Upgrading individual sessions requires you to specify the session's hostname. That allows HTTPie to find the correct file in the case of name sessions. Additionally, it allows it to correctly bind cookies when upgrading with [`--bind-cookies`](#session-upgrade-options).
```
([anonymous session](#anonymous-sessions))
```bash
$ httpie cli sessions upgrade pie.dev ./session.json
Refactored 'session' (for 'pie.dev') to the version 3.1.0.
```
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`.
Upgrade a single [named session](#named-sessions):
```bash
HTTPie uses a simple `config.json` file.
$ httpie cli sessions upgrade pie.dev api_auth
Upgraded 'api_auth' @ 'pie.dev' to v3.1.0
### Config file directory
To see the exact location for your installation, run `http --debug` and look for `config_dir` in the output.
```
Upgrade a single [anonymous session](#anonymous-sessions) using a file path:
The default location of the configuration file on most platforms is `$XDG_CONFIG_HOME/httpie/config.json` (defaulting to `~/.config/httpie/config.json`).
```bash
$ httpie cli sessions upgrade pie.dev ./session.json
Upgraded 'session.json' @ 'pie.dev' to v3.1.0
```
#### Session upgrade options
These flags are available for both `sessions upgrade` and `sessions upgrade-all`:
------------------|------------------------------------------
`--bind-cookies` | Bind all previously [unbound cookies](#host-based-cookie-policy) to the session’s host.
The config directory can be changed by setting the `$HTTPIE_CONFIG_DIR` environment variable:
## Config
HTTPie uses a simple `config.json` file.
The file doesn’t exist by default, but you can create it manually.
$ export HTTPIE_CONFIG_DIR=/tmp/httpie
### Config file directory
```
### Configurable options
To see the exact location for your installation, run `http --debug` and look for `config_dir` in the output.
Currently, HTTPie offers a single configurable option:
The default location of the configuration file on most platforms is `$XDG_CONFIG_HOME/httpie/config.json` (defaulting to `~/.config/httpie/config.json`).
For backward 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.
@@ -2342,7 +2306,7 @@ To see the exact location for your installation, run `http --debug` and look for
```json
{
"default_options": [
"default_options": [
"--style=fruity"
]
}