Thu, 23 Mar 2023 12:14:53 +0000
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 | ``` |