electron/docs/api/client-request.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

278 lines
10 KiB
Markdown
Raw Normal View History

2016-11-10 20:25:26 +00:00
## Class: ClientRequest
> Make HTTP/HTTPS requests.
feat: add net module to utility process (#40017) * chore: initial prototype of net api from utility process * chore: update url loader to work on both browser and utility processes * chore: add net files to utility process bundle * chore: re-add app ready check but only on main process * chore: replace browser thread dcheck's with sequence checker * refactor: move url loader from browser to common * refactor: move net-client-request.ts from browser to common * docs: add utility process to net api docs * refactor: move net module app ready check to browser only * refactor: switch import from main to common after moving to common * test: add basic net module test for utility process * refactor: switch browser pid with utility pid * refactor: move electron_api_net from browser to common * chore: add fetch to utility net module * chore: add isOnline and online to utility net module * refactor: move net spec helpers into helper file * refactor: break apart net module tests Adds two additional net module test files: `api-net-session-spec.ts` for tests that depend on a session being available (aka depend on running on the main process) and `api-net-custom-protocols-spec.ts` for custom protocol tests. This enables running `api-net-spec.ts` in the utility process. * test: add utility process mocha runner to run net module tests * docs: add utility process to net module classes * refactor: update imports in lib/utility to use electron/utility * chore: check browser context before using in main process Since the browser context supplied to the SimpleURLLoaderWrapper can now be null for use in the UtilityProcess, adding a null check for the main process before use to get a more sensible error if something goes wrong. Co-authored-by: Cheng Zhao <github@zcbenz.com> * chore: remove test debugging * chore: remove unnecessary header include * docs: add utility process net module limitations * test: run net module tests in utility process individually * refactor: clean up prior utility process net tests * chore: add resolveHost to utility process net module * chore: replace resolve host dcheck with sequence checker * test: add net module tests for net.resolveHost * docs: remove utility process limitation for resolveHost --------- Co-authored-by: deepak1556 <hop2deep@gmail.com> Co-authored-by: Cheng Zhao <github@zcbenz.com>
2024-01-04 21:20:37 +00:00
Process: [Main](../glossary.md#main-process), [Utility](../glossary.md#utility-process)<br />
_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
2016-11-10 20:25:26 +00:00
`ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams)
interface and is therefore an [EventEmitter][event-emitter].
2016-11-10 20:25:26 +00:00
### `new ClientRequest(options)`
* `options` (Object | string) - If `options` is a string, it is interpreted as
2016-11-10 20:25:26 +00:00
the request URL. If it is an object, it is expected to fully specify an HTTP request via the
following properties:
* `method` string (optional) - The HTTP request method. Defaults to the GET
method.
* `url` string (optional) - The request URL. Must be provided in the absolute
form with the protocol scheme specified as http or https.
* `session` Session (optional) - The [`Session`](session.md) instance with
which the request is associated.
* `partition` string (optional) - The name of the [`partition`](session.md)
with which the request is associated. Defaults to the empty string. The
`session` option supersedes `partition`. Thus if a `session` is explicitly
specified, `partition` is ignored.
2023-02-20 20:57:38 +00:00
* `credentials` string (optional) - Can be `include`, `omit` or
`same-origin`. Whether to send
[credentials](https://fetch.spec.whatwg.org/#credentials) with this
request. If set to `include`, credentials from the session associated with
the request will be used. If set to `omit`, credentials will not be sent
with the request (and the `'login'` event will not be triggered in the
2023-02-20 20:57:38 +00:00
event of a 401). If set to `same-origin`, `origin` must also be specified.
This matches the behavior of the
[fetch](https://fetch.spec.whatwg.org/#concept-request-credentials-mode)
option of the same name. If this option is not specified, authentication
data from the session will be sent, and cookies will not be sent (unless
`useSessionCookies` is set).
* `useSessionCookies` boolean (optional) - Whether to send cookies with this
request from the provided session. If `credentials` is specified, this
option has no effect. Default is `false`.
* `protocol` string (optional) - Can be `http:` or `https:`. The protocol
scheme in the form 'scheme:'. Defaults to 'http:'.
* `host` string (optional) - The server host provided as a concatenation of
the hostname and the port number 'hostname:port'.
* `hostname` string (optional) - The server host name.
2016-11-10 20:25:26 +00:00
* `port` Integer (optional) - The server's listening port number.
* `path` string (optional) - The path part of the request URL.
* `redirect` string (optional) - Can be `follow`, `error` or `manual`. The
redirect mode for this request. When mode is `error`, any redirection will
be aborted. When mode is `manual` the redirection will be cancelled unless
[`request.followRedirect`](#requestfollowredirect) is invoked synchronously
during the [`redirect`](#event-redirect) event. Defaults to `follow`.
* `origin` string (optional) - The origin URL of the request.
2023-02-20 20:57:38 +00:00
* `referrerPolicy` string (optional) - can be `""`, `no-referrer`,
`no-referrer-when-downgrade`, `origin`, `origin-when-cross-origin`,
`unsafe-url`, `same-origin`, `strict-origin`, or
`strict-origin-when-cross-origin`. Defaults to
`strict-origin-when-cross-origin`.
* `cache` string (optional) - can be `default`, `no-store`, `reload`,
`no-cache`, `force-cache` or `only-if-cached`.
2016-11-10 20:25:26 +00:00
`options` properties such as `protocol`, `host`, `hostname`, `port` and `path`
strictly follow the Node.js model as described in the
[URL](https://nodejs.org/api/url.html) module.
For instance, we could have created the same request to 'github.com' as follows:
```js
2016-11-10 20:25:26 +00:00
const request = net.request({
method: 'GET',
protocol: 'https:',
hostname: 'github.com',
port: 443,
path: '/'
})
```
### Instance Events
#### Event: 'response'
Returns:
2021-06-03 05:54:33 +00:00
* `response` [IncomingMessage](incoming-message.md) - An object representing the HTTP response message.
2016-11-10 20:25:26 +00:00
#### Event: 'login'
Returns:
* `authInfo` Object
* `isProxy` boolean
* `scheme` string
* `host` string
2016-11-10 20:25:26 +00:00
* `port` Integer
* `realm` string
2016-11-10 20:25:26 +00:00
* `callback` Function
* `username` string (optional)
* `password` string (optional)
2016-11-10 20:25:26 +00:00
Emitted when an authenticating proxy is asking for user credentials.
The `callback` function is expected to be called back with user credentials:
* `username` string
* `password` string
2016-11-10 20:25:26 +00:00
```js @ts-type={request:Electron.ClientRequest}
2016-11-10 20:25:26 +00:00
request.on('login', (authInfo, callback) => {
callback('username', 'password')
})
```
2016-11-10 20:25:26 +00:00
Providing empty credentials will cancel the request and report an authentication
error on the response object:
```js @ts-type={request:Electron.ClientRequest}
2016-11-10 20:25:26 +00:00
request.on('response', (response) => {
console.log(`STATUS: ${response.statusCode}`)
2016-11-10 20:25:26 +00:00
response.on('error', (error) => {
console.log(`ERROR: ${JSON.stringify(error)}`)
})
})
request.on('login', (authInfo, callback) => {
callback()
})
```
#### Event: 'finish'
Emitted just after the last chunk of the `request`'s data has been written into
the `request` object.
#### Event: 'abort'
Emitted when the `request` is aborted. The `abort` event will not be fired if
the `request` is already closed.
#### Event: 'error'
Returns:
* `error` Error - an error object providing some information about the failure.
Emitted when the `net` module fails to issue a network request. Typically when
the `request` object emits an `error` event, a `close` event will subsequently
follow and no response object will be provided.
#### Event: 'close'
Emitted as the last event in the HTTP request-response transaction. The `close`
event indicates that no more events will be emitted on either the `request` or
`response` objects.
2017-03-25 07:07:34 +00:00
#### Event: 'redirect'
Returns:
* `statusCode` Integer
* `method` string
* `redirectUrl` string
* `responseHeaders` Record<string, string[]>
2017-03-25 07:07:34 +00:00
Emitted when the server returns a redirect response (e.g. 301 Moved
Permanently). Calling [`request.followRedirect`](#requestfollowredirect) will
continue with the redirection. If this event is handled,
[`request.followRedirect`](#requestfollowredirect) must be called
**synchronously**, otherwise the request will be cancelled.
2017-03-25 07:07:34 +00:00
2016-11-10 20:25:26 +00:00
### Instance Properties
#### `request.chunkedEncoding`
A `boolean` specifying whether the request will use HTTP chunked transfer encoding
2016-11-10 20:25:26 +00:00
or not. Defaults to false. The property is readable and writable, however it can
be set only before the first write operation as the HTTP headers are not yet put
on the wire. Trying to set the `chunkedEncoding` property after the first write
will throw an error.
Using chunked encoding is strongly recommended if you need to send a large
request body as data will be streamed in small chunks instead of being
internally buffered inside Electron process memory.
### Instance Methods
#### `request.setHeader(name, value)`
* `name` string - An extra HTTP header name.
* `value` string - An extra HTTP header value.
2016-11-10 20:25:26 +00:00
Adds an extra HTTP header. The header name will be issued as-is without
2016-11-10 20:25:26 +00:00
lowercasing. It can be called only before first write. Calling this method after
the first write will throw an error. If the passed value is not a `string`, its
`toString()` method will be called to obtain the final value.
2016-11-10 20:25:26 +00:00
Certain headers are restricted from being set by apps. These headers are
listed below. More information on restricted headers can be found in
[Chromium's header utils](https://source.chromium.org/chromium/chromium/src/+/main:services/network/public/cpp/header_util.cc;drc=1562cab3f1eda927938f8f4a5a91991fefde66d3;bpv=1;bpt=1;l=22).
* `Content-Length`
* `Host`
* `Trailer` or `Te`
* `Upgrade`
* `Cookie2`
* `Keep-Alive`
* `Transfer-Encoding`
Additionally, setting the `Connection` header to the value `upgrade` is also disallowed.
2016-11-10 20:25:26 +00:00
#### `request.getHeader(name)`
* `name` string - Specify an extra header name.
2016-11-10 20:25:26 +00:00
Returns `string` - The value of a previously set extra header name.
2016-11-10 20:25:26 +00:00
#### `request.removeHeader(name)`
* `name` string - Specify an extra header name.
2016-11-10 20:25:26 +00:00
Removes a previously set extra header name. This method can be called only
before first write. Trying to call it after the first write will throw an error.
#### `request.write(chunk[, encoding][, callback])`
* `chunk` (string | Buffer) - A chunk of the request body's data. If it is a
2016-11-10 20:25:26 +00:00
string, it is converted into a Buffer using the specified encoding.
* `encoding` string (optional) - Used to convert string chunks into Buffer
2016-11-10 20:25:26 +00:00
objects. Defaults to 'utf-8'.
2017-07-24 08:29:03 +00:00
* `callback` Function (optional) - Called after the write operation ends.
2016-11-10 20:25:26 +00:00
`callback` is essentially a dummy function introduced in the purpose of keeping
similarity with the Node.js API. It is called asynchronously in the next tick
after `chunk` content have been delivered to the Chromium networking layer.
Contrary to the Node.js implementation, it is not guaranteed that `chunk`
content have been flushed on the wire before `callback` is called.
Adds a chunk of data to the request body. The first write operation may cause
the request headers to be issued on the wire. After the first write operation,
it is not allowed to add or remove a custom header.
#### `request.end([chunk][, encoding][, callback])`
* `chunk` (string | Buffer) (optional)
* `encoding` string (optional)
2016-11-10 20:25:26 +00:00
* `callback` Function (optional)
2023-03-27 17:00:55 +00:00
Returns `this`.
2016-11-10 20:25:26 +00:00
Sends the last chunk of the request data. Subsequent write or end operations
will not be allowed. The `finish` event is emitted just after the end operation.
#### `request.abort()`
Cancels an ongoing HTTP transaction. If the request has already emitted the
`close` event, the abort operation will have no effect. Otherwise an ongoing
event will emit `abort` and `close` events. Additionally, if there is an ongoing
response object,it will emit the `aborted` event.
2017-03-25 07:07:34 +00:00
#### `request.followRedirect()`
Continues any pending redirection. Can only be called during a `'redirect'`
event.
#### `request.getUploadProgress()`
Returns `Object`:
* `active` boolean - Whether the request is currently active. If this is false
no other properties will be set
* `started` boolean - Whether the upload has started. If this is false both
`current` and `total` will be set to 0.
* `current` Integer - The number of bytes that have been uploaded so far
* `total` Integer - The number of bytes that will be uploaded this request
You can use this method in conjunction with `POST` requests to get the progress
of a file upload or other data transfer.
[event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter