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.

166
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 # Client: XMPP client
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 The `[Client]` class represents an XMPP client connection to a server.
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 Example:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 ```
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 [Client] Romeo
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 jid: romeo@example.com
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 password: s3cr3t!
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 ```
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 ## Properties
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 | Property | Description |
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 |:-------------|:------------------------------------|
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 | jid | The JID to connect to the server as |
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 | password | The password to connect with |
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 | connect_host | The server host, if not the default |
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 | connect_port | The server port, if not the default |
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 ## Actions
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 ### sends
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 Sends a stanza to the XMPP server.
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 Example:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 ```
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 Romeo sends:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 <iq type="get" id="123">
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 <query xmlns="jabber:iq:roster"/>
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 </iq>
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 ```
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38 ### receives
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 Expects to receive a stanza from the server.
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 Example:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 ```
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 Romeo receives:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 <iq type="result" id="123">
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 <query xmlns="jabber:iq:roster">
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 <item jid="juliet@example.com" subscription="both" />
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 </query>
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 </iq>
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51 ```
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53 If no stanza is expected, the simple string 'nothing' may be used:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 ```
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 Romeo receives: nothing
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 ```
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 #### Matching rules
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61 When a stanza is received from the server, it is matched against the one in the script.
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 If it does not match, the script will fail and abort.
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 The matching has two modes, strict and non-strict. They require:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66 Non-strict mode:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68 - All attributes in the expected stanza must be present in the received stanza. Additional
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69 attributes in the received stanza are ignored.
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 - All tags in the expected stanza must be present in the received stanza. Additional tags are ignored. Order is ignored.
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72 Strict mode:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74 - All attributes in the expected stanza must be in the received stanza, and vice-versa. Additional attributes in the received stanza are not allowed.
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 - All tags in the expected stanza must be in the received stanza, additional tags are not allowed. Order must be the same.
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 Both modes:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79 - If an attribute value is `{scansion:any}` in the expected stanza, that attribute must be present in the received stanza, but
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80 the value itself is ignored. This is useful for e.g. id attributes or other attributes that may vary unpredictably.
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
81
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
82 By default tags in the default namespace are matched using the non-strict rules, but tags with their own namespace are matched using the
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
83 strict rules. You can override the matching behaviour for any tag by adding a `scansion:strict` attribute with a value of `true` or `false`:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
84
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
85 ```
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
86 # By default this would match any message, by ignoring
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87 # extra payloads. However we enable strict mode to ensure
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
88 # that it only matches a completely empty message stanza:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
89
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
90 Romeo receives:
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
91 <message scansion:strict="true"/>
5d39804f108b docs: Add initial documentation
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
92 ```

mercurial