docs/character-classes/client.md

Thu, 23 Mar 2023 12:14:53 +0000

author
Matthew Wild <mwild1@gmail.com>
date
Thu, 23 Mar 2023 12:14:53 +0000
changeset 172
2c17151ed21b
parent 166
5d39804f108b
permissions
-rw-r--r--

client: Fix timeout handling

Previously, the timeout handler would fire an error that would get caught and
logged by the timer code. However that error never reached the upper levels of
scansion, leading to the whole thing just hanging.

Now we just trigger resumption of the async runner, and throw the error from
there if we haven't received the stanza yet.

With this change, timeouts are now correctly handled and reported as failures.

# Client: XMPP client

The `[Client]` class represents an XMPP client connection to a server.

Example:

```
[Client] Romeo
	jid: romeo@example.com
	password: s3cr3t!
```


## Properties

| Property     | Description                         |
|:-------------|:------------------------------------|
| jid          | The JID to connect to the server as |
| password     | The password to connect with        |
| connect_host | The server host, if not the default |
| connect_port | The server port, if not the default |

## Actions

### sends

Sends a stanza to the XMPP server.

Example:

```
Romeo sends:
	<iq type="get" id="123">
		<query xmlns="jabber:iq:roster"/>
	</iq>
```

### receives

Expects to receive a stanza from the server.

Example:

```
Romeo receives:
	<iq type="result" id="123">
		<query xmlns="jabber:iq:roster">
			<item jid="juliet@example.com" subscription="both" />
		</query>
	</iq>
```

If no stanza is expected, the simple string 'nothing' may be used:

```
Romeo receives: nothing
```

#### Matching rules

When a stanza is received from the server, it is matched against the one in the script.
If it does not match, the script will fail and abort.

The matching has two modes, strict and non-strict. They require:

Non-strict mode:

- All attributes in the expected stanza must be present in the received stanza. Additional
attributes in the received stanza are ignored.
- All tags in the expected stanza must be present in the received stanza. Additional tags are ignored. Order is ignored.

Strict mode:

- All attributes in the expected stanza must be in the received stanza, and vice-versa. Additional attributes in the received stanza are not allowed.
- All tags in the expected stanza must be in the received stanza, additional tags are not allowed. Order must be the same.

Both modes:

- If an attribute value is `{scansion:any}` in the expected stanza, that attribute must be present in the received stanza, but
the value itself is ignored. This is useful for e.g. id attributes or other attributes that may vary unpredictably.

By default tags in the default namespace are matched using the non-strict rules, but tags with their own namespace are matched using the
strict rules. You can override the matching behaviour for any tag by adding a `scansion:strict` attribute with a value of `true` or `false`:

```
# By default this would match any message, by ignoring
# extra payloads. However we enable strict mode to ensure
# that it only matches a completely empty message stanza:

Romeo receives:
	<message scansion:strict="true"/>
```

mercurial