<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<refentry id="cockpit-http">
  <refnamediv>
    <refname>cockpit.js: HTTP Client</refname>
    <refpurpose>HTTP and REST API communication</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para>Cockpit allows access to local HTTP and REST services via this API.</para>
  </refsynopsisdiv>

  <refsection id="cockpit-http-constructor">
    <title>cockpit.http()</title>
<programlisting>
http = cockpit.http(endpoint, [options])
http = cockpit.http(options)
</programlisting>

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

    <variablelist>
      <varlistentry>
        <term><code>"address"</code></term>
        <listitem><para>Connect to an address other than localhost. Must be a valid host name or IP address.
          To use this option you also must provide a port number.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>"port"</code></term>
        <listitem><para>Port number to use with "address" option, when not given in <code>endpoint</code>.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>"tls"</code></term>
        <listitem><para>Object properties for an https connection. See
        <code><ulink url="https://github.com/cockpit-project/cockpit/blob/master/doc/protocol.md#payload-http-stream2">http-stream2 TLS options</ulink></code>.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>"connection"</code></term>
        <listitem><para>A connection identifier. Subsequent channel requests with the same
          identifier will try to use the same connection if it is still open.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><code>"headers"</code></term>
        <listitem><para>Additional HTTP headers to include with the HTTP request. This is a plain
          javascript object with each key as a header name, and each value as the header
          value.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><code>"superuser"</code></term>
        <listitem><para>Set to <code>"require"</code> to open this channel as root. If the
          currently logged in user is not permitted to become root (eg: via <code>pkexec</code>)
          then the <code>channel</code> will immediately be
          <link linkend="cockpit-channels-close-ev">closed</link> with a <code>"access-denied"</code>
          problem code.</para>
        <para>Set to <code>"try"</code> to try to make the request as root, but if that fails,
          fall back to perform an unprivileged request.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><code>"tls"</code></term>
        <listitem>
          <para>If set to a plain javascript object, then the connection will be an HTTPS
            connection and include TLS encryption. The fields of the <code>tls</code> object
            declare various TLS configuration and data. All fields are optional:</para>
          <itemizedlist>
            <listitem><para><code>"authority"</code>: Certificate authority(s) to expect as signers
              of the server's TLS certificate, represented as a plain javascript object.
              It should have either a <code>"file"</code> field containing a
              readable PEM file on the system containing authorities, or a <code>"data"</code> with
              PEM encoded certificate data.</para></listitem>
            <listitem><para><code>"certificate"</code>: A client certificate to use, represented as
              a plain javascript object. It should have either a <code>"file"</code> field containing a
              readable PEM file on the system to use as a certificate, or a <code>"data"</code> with
              PEM encoded certificate data.</para></listitem>
            <listitem><para><code>"key"</code>: A client key to use, represented as
              a plain javascript object. It should have either a <code>"file"</code> field containing a
              readable PEM file on the system to use as a key, or a <code>"data"</code> with
              PEM encoded key data.</para></listitem>
            <listitem><para><code>"validate"</code>: A boolean that describes whether to validate
              the server's TLS certificate or not. By default local connections are not validated,
              and remote connections are validated.</para></listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>

    </variablelist>

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

<programlisting>
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..."
        }
    }
});
</programlisting>

  </refsection>

  <refsection id="cockpit-http-get">
    <title>http.get()</title>
<programlisting>
request = http.get(path, [params, [headers]])
</programlisting>
    <para>Perform an HTTP GET request for the given <code>path</code>. If the <code>params</code>
      is specified it should be a plain javascript object, which will be turned into a query string.</para>
    <para>Optionally a plain javascript object containing headers can be included in the
      <code>headers</code> argument.</para>
    <para>The return value is a
      <ulink url="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</ulink>
      that will complete if the request happens successfully, or fail if there's a problem.</para>
  </refsection>

  <refsection id="cockpit-http-post">
    <title>http.post()</title>
<programlisting>
request = http.post(path, body, [headers])
</programlisting>
    <para>Perform an HTTP POST request for the given <code>path</code>. The <code>body</code>
      can be a string, or a javascript plain object, which will be encoded as JSON data. If
      <code>body</code> is <code>undefined</code> or <code>null</code> then an empty HTTP body
      will be sent.</para>
    <para>Optionally a plain javascript object containing headers can be included in the
      <code>headers</code> argument.</para>
    <para>The return value is a
      <ulink url="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</ulink>
      that will complete if the request happens successfully, or fail if there's a problem.</para>
  </refsection>

  <refsection id="cockpit-http-request">
    <title>http.request()</title>
<programlisting>
request = http.request(options)
</programlisting>
    <para>Perform an HTTP request. The <code>options</code> can contain the following:</para>

    <variablelist>
      <varlistentry>
        <term><code>"body"</code></term>
        <listitem><para>The HTTP request body. If you do not specify a body, then you must
          call <link linkend="cockpit-http-input">request.input()</link> to complete the body
          and allow the request to start.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>"headers"</code></term>
        <listitem><para>A javascript plain object containing HTTP headers.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>"method"</code></term>
        <listitem><para>The HTTP method. Defaults to <code>"GET"</code>.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>"params"</code></term>
        <listitem><para>A javascript plain object containing query string parameters.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>"path"</code></term>
        <listitem><para>The HTTP path. Defaults to <code>/</code>.</para></listitem>
      </varlistentry>
    </variablelist>

    <para>The return value is a
      <ulink url="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</ulink>
      that will complete if the request happens successfully, or fail if there's a problem.</para>
  </refsection>

  <refsection id="cockpit-http-then">
    <title>request.then()</title>
<programlisting>
request.then(data => { ... })
</programlisting>
    <para>This is a standard
      <ulink url="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</ulink>
      method. It sets up a handler to be called when the request finishes successfully.</para>
    <para>The <code>data</code> argument contains the body result of the request.
      If it a string, unless the process was opened in binary mode, in which case the
      <code>data</code> is an array of bytes. If a
      <code><link linkend="cockpit-http-stream">request.stream()</link></code>
      handler is set up, then any standard output data consumed by the handler will not
      be included in the <code>data</code> argument.</para>
  </refsection>

  <refsection id="cockpit-http-catch">
    <title>request.catch()</title>
<programlisting>
request.catch((exception[, data]) => { ... })
</programlisting>
    <para>This is a standard
      <ulink url="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</ulink> method.
      It sets up a handler to be called when the request fails, or returns an error code.</para>

    <para>The <code>exception</code> object passed to the handler can have the
      following fields:</para>

    <variablelist>
      <varlistentry>
        <term><code>problem</code></term>
        <listitem><para>A <link linkend="cockpit-problems">problem code</link> string when
          a problem occurred starting or communicating with the server. This is <code>null</code>
          if the process exited or was terminated.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>status</code></term>
        <listitem><para>The numeric status of the response. This is <code>null</code> if
          no response was received.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>reason</code></term>
        <listitem><para>A string reason returned in the response. This is <code>null</code> if
          no response was received.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>message</code></term>
        <listitem><para>A string message returned in the response. This is <code>null</code> if
          no response was received.</para></listitem>
      </varlistentry>
    </variablelist>

    <para>If the request returned a response body, it will be available in
      the <code>data</code> argument. Otherwise this argument will be <code>undefined</code>.</para>
  </refsection>

  <refsection id="cockpit-http-response">
    <title>request.response()</title>
<programlisting>
request.response((status, headers) => { ... })
</programlisting>
    <para>This sets up a handler to be called when the HTTP request gets the initial response
      from the server. The <code>status</code> argument is the HTTP status integer, and the
      <code>headers</code> is a plain javascript object containing the headers of the
      response.</para>
  </refsection>

  <refsection id="cockpit-http-stream">
    <title>request.stream()</title>
<programlisting>
request.stream(data => { ... })
</programlisting>
    <para>This sets up a handler to be called when the request returns output data. The
      handler will be called multiple times.</para>
    <para>Only one handler may be registered at a time. Registering an additional handler
      replaces the previous one. The handler receives either string <code>data</code> 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 <code>data</code>. Any data
      not consumed will be included again the next time the handler is called.</para>
    <para>If a <code>request.stream()</code> handler is set up, then the
      <code><link linkend="cockpit-http-then">request.then()</link></code> handlers will
      only get any remaining data not consumed by the stream handler.</para>
  </refsection>

  <refsection id="cockpit-http-input">
    <title>request.input()</title>
<programlisting>
request.input(data, [stream])
</programlisting>
    <para>This method writes <code>data</code> to the HTTP request body. It is only valid
      if no <code>"body"</code> has been specified in
      <link linkend="cockpit-http-request">http.request()</link> options. If <code>stream</code>
      is <code>true</code> then this function can be called again to provide further data.</para>
  </refsection>

  <refsection id="cockpit-http-close">
    <title>request.close()</title>
<programlisting>
request.close([problem])
</programlisting>
    <para>Cancel the request. If <code>problem</code> is specified it should be a
      standard <link linkend="cockpit-problems">problem code</link> string.</para>
  </refsection>

  <refsection id="cockpit-http-close-all">
    <title>http.close()</title>
    <programlisting>
http.close([problem])
    </programlisting>
    <para>Cancel all outstanding requests with the given problem code.  This is useful when
    you know that the server is going down soon.
    </para>
  </refsection>

</refentry>