Exampple.Client (exampple v0.9.1)
Client is a simple state machine inside of a process which helps us to create a client connection to a XMPP Server. The dynamic of the connection is contained inside of the client when we perform the connection and then we can send different kind of stanzas to the server.
The aim of this Client is to create a simple way to test the system but you can use it even to create bots based on XMPP.
It has the possibility to register templates and returns back the stanzas which are being received from the XMPP server to the calling process. This way we are responsible of the communication.
Templates
We have available the following templates:
init(domain): it sends the initial XML header. Requires the domain.starttls: sends the stanza to init the TLS negotiation (WIP).auth(user, password): send the auth stanza to the server.bind(resource): establish the bind to a resource.session: creates the session.presence: sends a presence.message(to, id, *kw_opts): build a message, it requires to specify different options. If we sendbody: "hello"then a body is created with that text as CDATA. We can also usepayload: "<body>Hello</body>"to define the payload by ourselves. And even specify atype.register(username, password): it sends the standard register stanza as is defined inside of the XEP-0077.
Checks
The checks are functions which check only the happy path, failing or raising an error if it's not finding what they need. We have defined the following checks:
auth: wait for thesuccessstanza from the server.init: wait forstream:featuresstanza andbindandsessionfeatures inside.bind: wait for the result IQ.presence: wait for the available presence as an echo from the server.
Link to this section Summary
Functions
Adds a check to be in use by the process when we call check/2 or
check/3. The name is the name or PID for the process, the key
is the name we will use storing the template and fun is the function
which will check the incoming stanza returning true or false if the
check is passed.
Adds a template to be in use by the process when we call send_template/2
or send_template/3. The name is the name or PID for the process, the
key is the name we will use storing the template and fun is the
function which will generate the stanza.
Use a check registered inside of the client verifying if the incoming
stanzas are passing the checks defined by the anonymous function. In
the same way as the send_template/3 function it provides to the
developer the ability to write better and shorter tests.
Returns a specification to start this module under a supervisor.
Send a message to the client process to start the connection. Optionally,
we can specify the name of the process where to connect, by default this
is the value provided by __MODULE__.
Send a message to the client process identified by name as PID
or registered process to stop the connection. The name parameter
is optional, by default it's set to __MODULE__.
Waits for an incoming connection / stanza which will be sent from
the client process. It only works if we are using this function
from the process which execute the start_link function or if
we passed the PID of the current process as the name parameter.
Optionally, we can configure a timeout, by default it's set to
5 seconds.
Same as get_conn/2 but we are waiting for a specific number
of stanzas to be received indicated by num parameter. We have
to indicate the name for the process where we are going to be
connected.
Ask to the process about whether the connection is active. The checks are based
on the process relanted to the passed name (it must be a registered name), the
PID should be valid and alive, and then we ask to the client if it's connected.
If no parameter is provided it is __MODULE__.
Waits for an incoming connection / stanza which will be sent from
the client process. It needs to define the stanza as the second
parameter to be catch. If the stanza arriving isn't which match,
it's giving a timeout. Optionally, we can configure a timeout,
by default it's set to 5 seconds.
Returns or true or a list of stanzas which were not found in the message queue.
Send information (stanzas) via the client process directly to the XMPP Server. These stanzas could be sent to whoever inside of the XMPP network locally or even to other domains if the network is federated.
Use a template registered inside of the client. This let us to trigger faster stanzas when we are working from the shell. But also reduce the amount of code when we are developing tests.
Starts the client. We can send a name to be registered or use
the module name (__MODULE__) by default. As args the
system requires a Map with the information for the connection.
The information we can provide is
Stops the process. You can specify the name of the process to be
stopped, by default this value is set as __MODULE__.
Performs a subscription to the XMPP client. This means the client is going to notify when it's connected. This could be used for testing and for synchronization at start. Only one process could be subscribed at the same time.
Upgrade a connection as TLS.
Wait until the system is connected to start processing messages. This is in use for functional tests and could be used as a phase in the start of the applications.
Link to this section Functions
add_check(name \\ __MODULE__, key, fun)
Specs
Adds a check to be in use by the process when we call check/2 or
check/3. The name is the name or PID for the process, the key
is the name we will use storing the template and fun is the function
which will check the incoming stanza returning true or false if the
check is passed.
add_template(name \\ __MODULE__, key, fun)
Specs
Adds a template to be in use by the process when we call send_template/2
or send_template/3. The name is the name or PID for the process, the
key is the name we will use storing the template and fun is the
function which will generate the stanza.
check!(template, args \\ [], name \\ __MODULE__)
Specs
Use a check registered inside of the client verifying if the incoming
stanzas are passing the checks defined by the anonymous function. In
the same way as the send_template/3 function it provides to the
developer the ability to write better and shorter tests.
We are providing the template name for the check, optionally some args
if the check requires it and the name of the process for the client,
by default it will be __MODULE__.
The return of the check should be a map, if you return an struct it will
be inserted inside of an empty map using the name of the struct as name.
For example, returning a %Conn{} it will result in a %{"conn" => %Conn{}}.
child_spec(init_arg)
Returns a specification to start this module under a supervisor.
See Supervisor.
connect(name \\ __MODULE__)
Specs
Send a message to the client process to start the connection. Optionally,
we can specify the name of the process where to connect, by default this
is the value provided by __MODULE__.
disconnect(name \\ __MODULE__)
Specs
Send a message to the client process identified by name as PID
or registered process to stop the connection. The name parameter
is optional, by default it's set to __MODULE__.
get_conn(name, timeout \\ 5000)
Specs
get_conn(atom() | pid(), timeout()) :: Exampple.Router.Conn.t() | :timeout
Waits for an incoming connection / stanza which will be sent from
the client process. It only works if we are using this function
from the process which execute the start_link function or if
we passed the PID of the current process as the name parameter.
Optionally, we can configure a timeout, by default it's set to
5 seconds.
get_conns(name, num, timeout \\ 5000)
Specs
get_conns(atom() | pid(), pos_integer(), timeout()) :: [ Exampple.Router.Conn.t() | :timeout ]
Same as get_conn/2 but we are waiting for a specific number
of stanzas to be received indicated by num parameter. We have
to indicate the name for the process where we are going to be
connected.
Optionally, we can configure a timeout, by default it's set to
5 seconds.
is_connected?(name \\ __MODULE__)
Specs
Ask to the process about whether the connection is active. The checks are based
on the process relanted to the passed name (it must be a registered name), the
PID should be valid and alive, and then we ask to the client if it's connected.
If no parameter is provided it is __MODULE__.
Waits for an incoming connection / stanza which will be sent from
the client process. It needs to define the stanza as the second
parameter to be catch. If the stanza arriving isn't which match,
it's giving a timeout. Optionally, we can configure a timeout,
by default it's set to 5 seconds.
receive_conns(name, stanzas, timeout \\ 5000)
Specs
receive_conns(atom() | pid(), [Exampple.Xml.Xmlel.t()], timeout()) :: {[Exampple.Xml.Xmlel.t()], [Exampple.Xml.Xmlel.t()]}
Returns or true or a list of stanzas which were not found in the message queue.
send(data_or_conn, name \\ __MODULE__)
Specs
send(binary() | Exampple.Router.Conn.t(), GenServer.server()) :: :ok
Send information (stanzas) via the client process directly to the XMPP Server. These stanzas could be sent to whoever inside of the XMPP network locally or even to other domains if the network is federated.
The accepted paramter data_or_conn could be a string (or binary)
or a Conn struct. Optionally, you can specify a second parameter
as the name of the registered process. The default value for the
name paramter is __MODULE__.
Example:
iex> Exampple.Client.send("<presence/>")
:oksend_template(template, args \\ [], name \\ __MODULE__)
Specs
Use a template registered inside of the client. This let us to trigger faster stanzas when we are working from the shell. But also reduce the amount of code when we are developing tests.
The template parameter is an atom, the key for the keyword
list of templates stored inside of the process. The args are
the arguments passed to the function template. Finally the name
is the name of the process where the request will be sent.
start_link(name \\ __MODULE__, args)
Specs
start_link(atom() | pid(), map()) :: GenStateMachine.on_start()
Starts the client. We can send a name to be registered or use
the module name (__MODULE__) by default. As args the
system requires a Map with the information for the connection.
The information we can provide is:
host: the hostname or IP where we will be connected.port: the port number where we will be connected.domain: the XMPP domain we are going to use.trimmed: if the stanzas will be trimmed (defaultfalse).set_from: if we are going to set thefromfor each stanza written by the client (defaultfalse).ping: if we active the ping. We can set here the number of milliseconds to send the ping or false to disable it (defaultfalse).tcp_handler: the module which we will use to handle the connection (defaultExampple.Tcp).tls_handler: the module which we will use to handle the TLS connection, if any (defaultExampple.Tls).
stop(name \\ __MODULE__)
Specs
Stops the process. You can specify the name of the process to be
stopped, by default this value is set as __MODULE__.
subscribe(name \\ __MODULE__)
Specs
Performs a subscription to the XMPP client. This means the client is going to notify when it's connected. This could be used for testing and for synchronization at start. Only one process could be subscribed at the same time.
upgrade_tls(name \\ __MODULE__)
Specs
Upgrade a connection as TLS.
wait_for_connected(name \\ __MODULE__)
Specs
Wait until the system is connected to start processing messages. This is in use for functional tests and could be used as a phase in the start of the applications.