cockpit.http()

http = cockpit.http(endpoint, [options])
http = cockpit.http(options)

Create a new HTTP client. The endpoint can be a file path starting with / to connect to a unix socket, or it can be a port number to connect to. The optional options argument is a javascript plain object, and may include:

Here is a somewhat complex example of using most of the above options when when calling cockpit.http():

http = cockpit.http({
    "address": "localhost",
    "headers": {
        "Authorization": "Basic dXNlcjpwYXNzd29yZA=="
    },
    "port": 443,
    "tls": {
        "validate": true,
        "authority": {
            "file": "/etc/pki/tls/certs/ca-bundle.crt",
        },
        "certificate": {
            "data": "-----BEGIN CERTIFICATE-----\nMIIDsDCCA..."
        },
        "key": {
            "data": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBA..."
        }
    }
});

http.get()

request = http.get(path, [params, [headers]])

Perform an HTTP GET request for the given path. If the params is specified it should be a plain javascript object, which will be turned into a query string.

Optionally a plain javascript object containing headers can be included in the headers argument.

The return value is a promise that will complete if the request happens successfully, or fail if there's a problem.

http.post()

request = http.post(path, body, [headers])

Perform an HTTP POST request for the given path. The body can be a string, or a javascript plain object, which will be encoded as JSON data. If body is undefined or null then an empty HTTP body will be sent.

Optionally a plain javascript object containing headers can be included in the headers argument.

The return value is a promise that will complete if the request happens successfully, or fail if there's a problem.

http.request()

request = http.request(options)

Perform an HTTP request. The options can contain the following:

The return value is a promise that will complete if the request happens successfully, or fail if there's a problem.

request.done()

request.done(function(data) { ... })

This is a standard promise method. It sets up a handler to be called when the request finishes successfully.

The data argument contains the body result of the request. If it a string, unless the process was opened in binary mode, in which case the data is an array of bytes. If a request.stream() handler is set up, then any standard output data consumed by the handler will not be included in the data argument.

request.fail()

request.fail(function(exception[, data]) { ... })

This is a standard jQuery promise method. It sets up a handler to be called when the request fails, or returns an error code.

The exception object passed to the handler can have the following fields:

If the request returned a response body, it will be available in the data argument. Otherwise this argument will be undefined.

request.always()

request.always(function() { ... })

This is a standard jQuery promise method. It sets up a handler to be called when the process completes, whether it exits successfully, fails, terminates, or exits with a failure.

request.response()

request.response(function(status, headers) { ... })

This sets up a handler to be called when the HTTP request gets the initial response from the server. The status argument is the HTTP status integer, and the headers is a plain javascript object containing the headers of the response.

request.stream()

request.stream(function(data) { ... })

This sets up a handler to be called when the request returns output data. The handler will be called multiple times.

Only one handler may be registered at a time. Registering an additional handler replaces the previous one. The handler receives either string data or an array of binary bytes as its argument. A stream handler may return a number, which indicates the number of characters or bytes consumed from data. Any data not consumed will be included again the next time the handler is called.

If a request.stream() handler is set up, then the request.done() handlers will only get any remaining data not consumed by the stream handler.

request.input()

request.input(data, [stream])

This method writes data to the HTTP request body. It is only valid if no "body" has been specified in http.request() options. If stream is true then this function can be called again to provide further data.

request.close()

request.close([problem])

Cancel the request. If problem is specified it should be a standard problem code string.

http.close()

http.close([problem])
    

Cancel all outstanding requests with the given problem code. This is useful when you know that the server is going down soon.