open Markup

exception MalformedStanza of location * 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] disconnects brutally the underlying XMPP server and closes [_socket],
    without closing the element stream first. *)
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

(** [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

(** [close] is a stream of signals that close the Portal, indicating to the XMPP server
    that the connection is closed. Namely, it does {b not} interact with the Portal in
    any way: It's the caller's job to provide it to the stream. *)
val close : (signal, sync) stream

(** [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. *)
val starttls : t -> unit Lwt.t