# `httpupload` — HTTP Upload support (XEP-0363)

The XEP-0363 HTTP Upload protocol allows an XMPP client to obtain a PUT and GET URL for storage on the server. It can upload a file (once) using the PUT URL and distribute access to the file via the GET url.

This module does not handle the HTTP part of the interaction. We recommend to use `aiohttp` for this, but you can use any HTTP library which supports GET, PUT and sending custom headers.

Example use:

    client = <your aioxmpp.Client>
    slot = await client.send(aioxmpp.httpupload.Request(
        filename,
        size,
        content_type,
    ))
    # http_put_file is provided by you via an HTTP library
    await http_put_file(
        slot.put.url,
        slot.put.headers,
        filename
    )

coroutine `aioxmpp.httpupload.``request_slot`(client, service: aioxmpp.structs.JID, filename: str, size: int, content_type: str)

  Request an HTTP upload slot.

  Parameters:

  - client (`aioxmpp.Client`) – The client to request the slot with.
  - service (`JID`) – Address of the HTTP upload service.
  - filename (`str`) – Name of the file (without path), may be used by the server to generate the URL.
  - size (`int`) – Size of the file in bytes
  - content_type (`str`) – The MIME type of the file

  Returns: | The assigned upload slot.
  Return type: | `xso.Slot`

  Sends a XEP-0363 slot request to the XMPP service to obtain HTTP PUT and GET URLs for a file upload.

  The upload slot is returned as a `Slot` object.

class `aioxmpp.httpupload.``Request`(filename, size, content_type)

  XSO to request an upload slot from the server.

  The parameters initialise the attributes below.

  `filename` : str

    The file name (without path, but possibly with “extension”) of the file to upload. The server MAY use this in the URL.

  `size` : int

    The size of the file in bytes. This must be accurate and MUST also be used as `Content-Length` header in the PUT request.

  `content_type` : str

    The MIME type of the file. This MUST be set in the PUT request as `Content-Type` header.

class `aioxmpp.httpupload.xso.``Slot`

  XSO representing the an upload slot provided by the server.

  `get`

    Information about the GET request for the slot as `Get` XSO.

  `put`

    Information about the PUT request for the slot as `Put` XSO.

class `aioxmpp.httpupload.xso.``Get`
  `url` : str

    The URL at which the file can be retrieved after uploading.

class `aioxmpp.httpupload.xso.``Put`
  `url` : str

    The URL against which the PUT request must be made.

  `headers` : multidict.MultiDict

    The headers which MUST be used in the PUT request as `multidict.MultiDict`, in addition to the `Content-Type` and `Content-Length` headers.

    The headers are already sanitised according to XEP-0363 (see also `HEADER_WHITELIST`).

  `HEADER_WHITELIST`

    This class attribute holds the list of headers which are allowed to be used by the server. This defaults to the list specified in XEP-0363.

    Warning

    Changing the list of allowed headers may have unintended security implications.