open Markup

exception MalformedStanza of Error.t

type socket

(** The type of portals communicating with an XMPP server via [_socket].

    [stream] is the data sent by the XMPP server.

    [push None] closes the XMPP stream and disconnects the underlying [_socket]. This is
    how XMPP streams should be ended. *)
type t = {
    mutable stream : (signal, async) stream;
    mutable push : (signal, sync) stream option -> unit;
    mutable _socket : socket;
  }

(** This is the XML namespace of the underlying element stream.

    You can rely on it on your code, as an escape hatch, but you should probably not,
    since the Portal interface is supposed to be agnostic. *)
val xmlns : string

(** [connect domain] returns a Portal connected to the XMPP server [domain]. *)
val connect : string -> t Lwt.t

(** [starttls portal] mutates [portal] into a TLS-encrypted stream with the same state.

    Note that when you call this function, the [stream] and [push] of the Portal are
    invalidated, and need to be regenerated using [header] (this should always be done
    anyways, according to the XMPP spec). *)
val starttls : t -> unit Lwt.t

(** [header domain portal] sends an initial stream header to the XMPP server [portal]
    addressed to [domain]. It returns the server-assigned [id] of the stream included in
    the response stream header.

    When [from] is specified, a from attribute is included. *)
val header : ?from:string -> string -> t -> string Lwt.t