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

134
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,43 +2213,32 @@ $ http --session=./session.json pie.dev/cookies
```json
{
"cookies": {
"__meta__": {
"foo": {
"expires": null,
"path": "/",
"secure": false,
"value": "bar"
"auth": {
}
"type": null,
}
}
},
```
"foo": {
In summary:
- 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.
- 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:
Upgrade all existing [named sessions](#named-sessions) inside the `sessions` subfolder of your [config directory](https://httpie.io/docs/cli/config-file-directory):
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`
```bash
$ httpie cli sessions upgrade-all
Upgraded 'api_auth' @ 'pie.dev' to v3.1.0
@@ -2279,57 +2250,50 @@ To set a cookie within a Session there are three options:
Upgrade a single [named session](#named-sessions):
```bash
([anonymous session](#anonymous-sessions))
```bash
$ httpie cli sessions upgrade pie.dev api_auth
Upgraded 'api_auth' @ 'pie.dev' to v3.1.0
Refactored 'session' (for 'pie.dev') to the version 3.1.0.
```
```
Upgrade a single [anonymous session](#anonymous-sessions) using a file path:
that this won't upgrade [anonymous sessions](#anonymous-sessions)):
```bash
```bash
$ httpie cli sessions upgrade-all
$ httpie cli sessions upgrade pie.dev ./session.json
Upgraded 'session.json' @ 'pie.dev' to v3.1.0
```
Refactored 'login_cookies' (for 'httpie.io') to the version 3.1.0.
```
#### Session upgrade options
These flags are available for both `sessions upgrade` and `sessions upgrade-all`:
| 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`).
------------------|------------------------------------------
`--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"
]
}