type

type stores the type of the session. A current list of defined types:

c2s

A fully established client-to-server session, which has authenticated and bound a resource.

c2s_unbound

A client-to-server session, which has authenticated but not yet bound a resource

c2s_unauthed

A client-to-server session, which is not yet authenticated

s2s

A fully established server-to-server session which has authenticated

s2s_unauthed

A server-to-server session, which has not yet been authenticated (via SASL/TLS/dialback or otherwise)

local

A local host, which the current server is serving

component

A component, local to this running server

base_type

Like type but without the suffixes (e.g. _unauthed). Remains the same throughout the sessions lifetime.

id

Session identifier. Usually a hexadecimal number. Used to identify the session in logs.

log()

session.log("info", "Hello, here I am")

Logs something like:

c2sa0372336    info    Hello, here I am

The log tag consists of base_type and id.

conn

conn is the underlying TCP connection for the session. It is rare you need to use this, though it is used to initiate TLS handshaking, etc.

notopen

The notopen flag is initially true on newly-created sessions, and is set to nil when the client sends an opening stream header. It is reset to true when the client needs to send a new stream header to continue (i.e. stream restarts after TLS, SASL negotiation).

send(x)

Sends a stanza to the session. Note that while x may currently be a string, this may be deprecated in the future.

close(reason)

Closes the session, for the given reason, if any.

reason may be:

• A string, in which case it is the name of one of the defined stream errors.
• A table, which must have 2 fields; ‘condition’ (as the string above) and ‘text’, which will be additional text provided to the remote user.
• A stanza, which will simply be sent before closing the stream, session, and connection.

nil or no reason will simply cleanly close and disconnect the session.

secure

secure specifies whether the session’s connection is currently protected by any form of encryption, SSL/TLS/etc..

username

username holds the username of the user, and only exists when the session is authenticated.

host

host contains the hostname of the server which the client connected to. Present from stream-opening onwards, although will change if the client authenticates to a new host afterwards.

resource

resource has the resource for the connection, and is present from resource-binding onwards.

full_jid

full_jid is the full, authenticated JID of the user. It is only present for connected resources (i.e. after resource-binding has been successful).

ip

The client’s IP address as a string in either IPv4 or IPv6 form. For BOSH sessions Prosody will attempt to use the client’s real IP here if they are connecting through a trusted proxy (see the ‘trusted_proxies’ option).

priority

priority records the priority last pushed via presence from this session.

presence

presence is the last non-directed “available” presence stanza. Initially nil, and reset to nil on unavailable presence.

interested

interested is true if the resource requested the roster. Interested resources receive roster updates.

roster

roster is the user’s Roster objects. Loaded as soon as the resource is bound (session becomes a connected resource).

direction

direction is either ‘incoming’ or ‘outgoing’ depending on the direction of the stream.

to_host

to_host is the domain of the server that the stream is connected *to*. For incoming sessions, this will be a local host, for outgoing it will be a remote host.

from_host

from_host is the domain of the server that the stream is from. For incoming sessions, this will be a remote host, for outgoing it will be a local host.