testkit only.Expand description
Backend conformance suite for ChatBackend implementations.
Gated behind feature = "testkit". Each test is a pub async fn
generic over ConformanceBackend, drives the backend through this
crate’s method handlers, and states its oracle (draft or RFC text) in
its rustdoc. A backend crate runs the whole suite with one
ConformanceBackend impl and one macro line in an integration test:
// tests/backend_conformance.rs
jmap_chat_server::chat_backend_conformance!(MyBackend::new_for_test);chat_backend_conformance! emits
one #[test] per suite test, each calling the given constructor for a
fresh, empty backend and running the test through run, so the
calling crate needs no tokio macros.
§What the suite assumes
Every test runs in one account, a1, which it registers with
ConformanceBackend::add_account; a few register further accounts.
Requests act as the owner of the account
(ConformanceBackend::caller). Fixtures are hand-written JSON
stored with ConformanceBackend::seed.
§Capability-gated tests
A test whose assertion holds only for some backend configurations returns early, and so passes, when the backend does not have that configuration:
- The
replyCount/unreadReplyCounttests checkChatLimits::supports_threadsfromChatSettings::limits; one test runs only when it isfalse, the others only when it istrue. Run the macro once per configuration to cover both. - The exact
Chat.unreadCounttests run only whenChatSettings::maintains_unread_countisfalse, where this crate keeps the count exact. draft-atwood-jmap-chat-00 §ChatunreadCountlets a backend that keeps the count itself update it “some time after the change that affects it” and “report a server-defined maximum”. - The outbound-event test runs only when
ConformanceBackend::take_outbound_eventsreturnsSome.
Traits§
- Conformance
Backend - The test seam a
ChatBackendimplements to run the conformance suite.
Functions§
- absent_
last_ read_ counts_ every_ message - aa01dd7 L635: candidates are “all Messages in the Chat if
lastReadMessageIdis absent.” Only Messages “in this Chat” count, sohhas 1. - anchor_
absent_ from_ results_ is_ anchor_ not_ found - RFC 8620 §5.5: “If the anchor is not found, the call is rejected with an “anchorNotFound” error.“
- anchor_
arguments_ of_ wrong_ type_ are_ invalid_ arguments - RFC 8620 §5.5 argument types: “anchor: “Id|null”“ and “anchorOffset: “Int” (default: 0)“; RFC 8620 §3.6.2 ““invalidArguments”: One of the arguments is of the wrong type or is otherwise invalid“.
- anchor_
offset_ before_ start_ clamps_ to_ zero - RFC 8620 §5.5: “If the resulting index is now negative, it is clamped to 0.”
- anchor_
offset_ without_ anchor_ is_ ignored - RFC 8620 §5.5: “If no “anchor” is supplied, any “anchorOffset” argument MUST be ignored.“
- anchor_
overrides_ position - RFC 8620 §5.5: “If an “anchor” is specified, any position argument supplied by the client MUST be ignored.“
- anchor_
with_ negative_ offset_ starts_ before_ anchor - RFC 8620 §5.5 anchorOffset: “This MAY be negative. For example, “-1” means the Foo immediately preceding the anchor is the first result in the list returned“.
- anchor_
with_ positive_ offset_ starts_ after_ anchor - RFC 8620 §5.5: “If an “anchor” argument is given, the anchor is looked for in the results after filtering and sorting. If found, the “anchorOffset” is then added to its index. … This index is now used exactly as though it were supplied as the “position” argument.“
- anchor_
without_ offset_ starts_ at_ anchor - RFC 8620 §5.5 anchorOffset: “(default: 0)”. Without an offset the anchor itself is the first result.
- chat_
destroy_ destroys_ its_ read_ position - L993: the server “destroys it when the Chat is destroyed”; RFC 8620
§5.1 makes
ReadPosition/changesreport it. - chat_
muted_ null_ resets_ to_ false - Oracle: draft-atwood-jmap-chat-00 Chat
muted: “Whentrue, push notifications for this chat are suppressed. […] Default:false.” - chat_
pinned_ message_ ids_ null_ resets_ to_ empty - Oracle: draft-atwood-jmap-chat-00 Chat
pinnedMessageIds: “Ordered list of pinned Message ids, most-recently-pinned first. […] Empty by default.” - chat_
query_ applies_ filter_ operators - RFC 8620 §5.5
FilterOperator: “AND: All of the conditions must match for the filter to match. OR: At least one of the conditions must match for the filter to match. NOT: None of the conditions must match for the filter to match.” - chat_
query_ filters_ kind_ and_ muted - L1139 (jmap-chat-spec 33702a5) §Chat/query: “Filter properties:
kind(String),muted(Boolean).” - chat_
receipt_ sharing_ null_ removes_ override - Oracle: draft-atwood-jmap-chat-00 Chat
receiptSharing(line 645-646 at spec 29e9a41): “(Boolean, optional) Per-Chat override of the account-levelPresenceStatus.receiptSharingpreference … When absent, the account-level preference applies.” The property has no default, sonullremoves the override and/getomits it (bd:JMAP-w9ox.2). - chat_
receive_ typing_ indicators_ null_ resets_ to_ true - Oracle: draft-atwood-jmap-chat-00 Chat
receiveTypingIndicators: “Default:true.” - client_
last_ read_ at_ is_ rejected - L1004
lastReadAtis server-set: a client write isinvalidProperties(RFC 8620 §5.3) and the record is unchanged. - compliance_
11_ 1_ unread_ count_ from_ read_ position - Compliance §11.1: “Send 5 messages. Set
ReadPositionto message 3. CallChat/get. VerifyunreadCountis 2 (messages 4 and 5).” - compliance_
11_ 1_ with_ assigned_ ids - Compliance §11.1 with server-assigned ids: “Send 5 messages. Set
ReadPositionto message 3. CallChat/get. VerifyunreadCountis 2 (messages 4 and 5).” The count holds only if, per L675, “Message IDs are ULIDs […] lexicographically ordered by time”, including for messages sent within the same millisecond (bd:JMAP-nls1). - concurrent_
redemptions_ increment_ exactly_ once - draft-atwood-jmap-chat-00 §Space/join (jmap-chat-spec 77c3474 L1416):
“The
usesincrement and membership insertion SHOULD be performed within a single atomic operation”, which this crate requires by choice. Concurrent redemptions are serialized: exactly one succeeds,usesis incremented exactly once and the member appears exactly once. - contact_
blocked_ null_ resets_ to_ false - Oracle: draft-atwood-jmap-chat-00
ChatContactblocked: “Whentrue, messages from thisChatContactare silently dropped by this mailbox […] Default:false.” - contact_
create_ by_ identity_ assigns_ id - draft-atwood-jmap-chat-00 §ChatContact/set: “
createaccepts onlyidentity, which is required; the server assignsidand sets the other server-set properties.” - contact_
create_ existing_ identity_ already_ exists - draft-atwood-jmap-chat-00 §ChatContact/set: “If a
ChatContactwith thatidentityalready exists, the server MUST reject the create with aSetErrorof typealreadyExists, including the existingChatContact’s id in theexistingIdfield ({{RFC8620}} Section 5.3).” - contact_
create_ other_ properties_ invalid_ properties - draft-atwood-jmap-chat-00 §ChatContact/set: “
createaccepts onlyidentity”. Any other property in a create is rejected with an RFC 8620 §5.3invalidPropertiesSetErrornaming it, and noChatContactis recorded. - contact_
create_ without_ identity_ invalid_ properties - draft-atwood-jmap-chat-00 §ChatContact/set: “
createaccepts onlyidentity, which is required”. A create withoutidentityis an invalid record (RFC 8620 §5.3invalidProperties). - contact_
query_ filters_ blocked_ and_ presence - L1064 (jmap-chat-spec 33702a5) §ChatContact/query: “Filter
properties:
blocked(Boolean),presence(String),identity(String; …).” - contact_
query_ identity_ filter_ matches_ octet_ for_ octet - draft-atwood-jmap-chat-00 §ChatContact/query: “Filter properties:
blocked(Boolean),presence(String),identity(String; matches theChatContactwhoseidentityequals the value octet for octet).” The case-variant contact shows the match is octet-exact. - contact_
query_ sort_ last_ active_ at_ absent_ sorts_ last - draft-atwood-jmap-chat-00 §ChatContact/query: “When sorting by
lastActiveAt,ChatContacts for which the field is absent sort last.” in both directions. - counts_
absent_ without_ supports_ threads - L639 / L642 (jmap-chat-spec 91672c9) “Present only when
supportsThreadsistrue”: withsupportsThreads: falseneither count is returned. - create_
message_ stores_ and_ reports_ one_ new_ message - Creates one Message and checks the stored Message, the state change
and the single
NewMessageevent against the spec. - create_
then_ get - Oracle: created objects are retrievable by id.
- emoji_
query_ changes_ applies_ space_ id_ filter - RFC 8620 §5.6:
CustomEmoji/queryChangeswith the query’sspaceIdfilter adds only emoji that the query matches. - emoji_
query_ filters_ space_ id - L1482 (jmap-chat-spec 33702a5) §CustomEmoji/query: “Filter
properties:
spaceId(String, optional — if absent returns all emoji accessible to the account including server-global).” - emoji_
query_ wrongly_ typed_ args_ do_ not_ echo_ value - RFC 8620 §5.5 types
limitas “UnsignedInt|null” andpositionas “Int”; wrong types areinvalidArguments(§3.6.2). The description names only the JSON type: §3.6.1 reserves it for “unstructured English text suitable for displaying to a developer”, so the client-supplied value is never echoed (bd JMAP-zegc).CustomEmoji/queryparses these arguments itself rather than throughjmap_server::handle_query. - exhausted_
invite_ is_ refused_ without_ any_ write - draft-atwood-jmap-chat-00 §Space/join: “… so that concurrent
redemptions cannot exceed
maxUses”: the backend re-checksmaxUsesitself rather than trusting the handler’s earlier read, and the refusal writes nothing. - expires_
after_ read_ seconds_ counts_ from_ read_ at - L753 (jmap-chat-spec 77c3474), §Message
expiresAfterReadSeconds: “the receiving server SHOULD permanently hard-delete this message (row removal, not tombstone) this many seconds after settingreadAt.” - expiry_
records_ chat_ unread_ count_ change - jmap-chat-spec aa01dd7 L635, §Chat
unreadCount: “Candidates are the Messages whoseidULID is lexicographically greater thanReadPosition.lastReadMessageId, or all Messages in the Chat iflastReadMessageIdis absent.” An expired Message lowers that count, and RFC 8620 §5.1 (“If the data changes, this string MUST change”) then requires theChatstate to move (bd:JMAP-y3f2.18). - extreme_
position_ and_ limit_ saturate - RFC 8620 §1.3 bounds
Intto “-2^53+1 <= value <= 2^53-1” andUnsignedIntto “0 <= value <= 2^53-1”. §5.5 position: “the negative value MUST be added to the total number of results given the filter, and if still negative, it’s clamped to “0”“, so the most negative legalpositionstarts at index 0, and the largest legallimitreturns all five results (bd:JMAP-uqhn.2). - invalid_
read_ at_ patch_ is_ rejected_ without_ burning - Oracle: draft-atwood-jmap-chat-00 (jmap-chat-spec 77c3474 L750)
§Message
burnOnRead: “Whentrue, the receiving server SHOULD permanently hard-delete this message (row removal, not tombstone) immediately after settingreadAt.” This crate performs the recommended deletion, so thereadAtwrite is never stored without it. - is_
contact_ blocked_ reads_ chat_ contact_ blocked_ field - Oracle:
is_contact_blockedreadsChatContact.blockedfrom the store. The backend’s predicate is exercised directly, mirroring the way a consumer’s transport layer would consult it before a fan-out. - is_
contact_ blocked_ reads_ only_ the_ owner_ list - Oracle: draft-atwood-jmap-chat-00 §Blocked Contacts (L1698): “Typing and
presence push events whose sending or referenced
ChatContacthasblocked: trueon the receiving owner’s contact list are similarly dropped”, and §ChatContactid(L426): “It identifies theChatContactonly on this server”. Two accounts each hold aChatContactfor the other; only the recipient’s own list decides, and a contact id is never resolved in another account’s list. - join_
adds_ member_ and_ counts_ use_ together - draft-atwood-jmap-chat-00 §Space/join: “… atomically increment
usesand add the caller to the Space’s member list”: one join produces both effects, each recorded as a change. - largest_
position_ is_ empty_ page_ not_ error - RFC 8620 §5.5 position: “If the index is greater than or equal to the total number of objects in the results list, then the “ids” array in the response will be empty, but this is not an error.“
- message_
actions_ null_ resets_ to_ empty - Oracle: draft-atwood-jmap-chat-00 Message
actions: “Out-of-band action invitations associated with this message. Empty by default.” - message_
broadcast_ mentions_ null_ resets_ to_ empty - Oracle: draft-atwood-jmap-chat-00 Message
broadcastMentions: “Structured broadcast-scope mention annotations […]. Empty by default.” - message_
destroy_ advances_ chat_ state - Destroying an unread Message lowers the Chat’s
unreadCount(L629), soChat/changesreports that Chat (RFC 8620 §5.2). - message_
expiry_ seconds_ deletes_ messages_ older_ than_ policy - L581 (jmap-chat-spec 91672c9), §Chat
messageExpirySeconds: “When set and non-zero, messages in this chat older than this many seconds are deleted by this mailbox.” L654, §MessagereceivedAt: “Authoritative for ordering and expiry calculations.” - message_
mentions_ null_ resets_ to_ empty - Oracle: draft-atwood-jmap-chat-00 Message
mentions: “Structured per-user @mention annotations. Empty by default.” - message_
query_ changes_ refuses_ text_ filter - L1279 (jmap-chat-spec 33702a5) §Message/query
text: “Servers that do not support full-text search MUST returnunsupportedFilter.” - message_
query_ changes_ requires_ chat_ id_ or_ has_ mention - L1269: “Servers MUST return an
unsupportedFiltererror for any request that omitschatIdwithout also includinghasMention: true” applies toMessage/queryChangestoo. - message_
query_ filters_ has_ attachment_ both_ ways - L1288 (jmap-chat-spec 33702a5)
hasAttachment: “Filter to messages with or without attachments.” - message_
query_ filters_ topic_ id - L1285 (jmap-chat-spec 33702a5)
topicId: “Return only messages whosetopicIdequals this value.” - message_
query_ has_ mention_ false_ excludes_ mentions - L1291 (jmap-chat-spec 33702a5)
hasMention: “Filter to messages that mention the owner: the accountId appears inmentions, OR …” - message_
reactions_ null_ resets_ to_ empty - Oracle: draft-atwood-jmap-chat-00 Message
reactions: “Emoji reactions, keyed bysenderReactionId. […] Empty object by default.” - mute_
until_ clears_ muted_ and_ mute_ until - L559 (jmap-chat-spec 91672c9), §Chat
muteUntil: “Muting expires at this time. Servers SHOULD clearmutedandmuteUntilautomatically when the time passes.” - path_
depth_ counts_ toward_ nesting_ cap - Oracle: bd:JMAP-wlip.1 caps
/set updatenesting at 32 levels and rejects deeper patches as RFC 8620 §5.3 “invalidPatch”, leaving the record unchanged. Because §5.3 makes keys “a path in JSON Pointer format”, the path itself reaches into the object, so its segments count toward the cap. Test vector: a 21-segment path into an existing 21-level value, setting another 21-level value, would store 43 levels; each repeat could add 21 more. - path_
key_ updates_ nested_ member - Oracle: RFC 8620 §5.3: “The keys are a path in JSON Pointer format
[RFC6901], with an implicit leading “/”“. The key
deliveryReceipts/u2therefore adds memberu2of thedeliveryReceiptsobject, keepingu1, rather than creating a property literally nameddeliveryReceipts/u2. - path_
through_ absent_ parent_ is_ invalid_ patch - Oracle: RFC 8620 §5.3: “All parts prior to the last (i.e., the value
after the final slash) MUST already exist on the object being
patched.” and “if there is any violation, the update MUST be
rejected with an “invalidPatch” error“. A fresh Message has no
deliveryReceipts, sodeliveryReceipts/u1is rejected and the stored Message is unchanged. - prefix_
conflict_ is_ invalid_ patch - Oracle: RFC 8620 §5.3: “There MUST NOT be two patches in the
PatchObjectwhere the pointer of one is the prefix of the pointer of the other, e.g., “alerts/1/offset” and “alerts”.“ and “if there is any violation, the update MUST be rejected with an “invalidPatch” error“. The stored Message is unchanged. - presence_
expires_ at_ resets_ status - L941-942 (jmap-chat-spec 91672c9), §
PresenceStatusexpiresAt: “If set, the server SHOULD clearstatusTextandstatusEmoji(setting them to null) at this time, and SHOULD resetpresenceto"online".” - presence_
null_ resets_ to_ online - Oracle: draft-atwood-jmap-chat-00
PresenceStatuspresence: “One of"online","away","busy","invisible", or"offline". Default is"online".” - presence_
receipt_ sharing_ null_ resets_ to_ true - Oracle: draft-atwood-jmap-chat-00
PresenceStatusreceiptSharing: “Whenfalse, this account does not send read receipts to peers. […] Default:true.” - read_
burn_ on_ read_ message_ is_ deleted - L750 (jmap-chat-spec 77c3474), §Message
burnOnRead: “the receiving server SHOULD permanently hard-delete this message (row removal, not tombstone) immediately after settingreadAt.” - read_
position_ set_ advances_ chat_ state - L1434 “updates
Chat.unreadCountfor the affected Chat” changes Chat data, so (RFC 8620 §5.1) the Chat state moves and (§5.2)Chat/changeslists only the affected Chat. - read_
position_ set_ updates_ last_ read_ at - L1434: “The server sets
lastReadAtto the current time”. - read_
position_ update_ lists_ thread_ root_ updated - RFC 8620 §5.1: “If the data changes, this string MUST change.”
Moving
lastReadMessageIdfrom A to C (L641-642, ids ordered per L591) marks reply C to ROOT read, so ROOT’sunreadReplyCountdrops from 1 to 0 and ROOT is listed as updated. B also crosses the read mark, but its parent A has athreadRootId, carries nounreadReplyCount, and is not listed. - read_
rules_ spare_ the_ senders_ own_ copy - L660 and L663 (jmap-chat-spec 91672c9), both rules: “Applies only to the receiving mailbox; the sender’s own copy is not affected.”
- remove_
channels_ destroys_ their_ read_ positions - L993 “destroys it when the Chat is destroyed” holds for a channel
removed by
Space/setremoveChannels. - reply_
counts_ match_ fixture - L638-642 (jmap-chat-spec 91672c9) against the fixture, counted by hand:
- reply_
create_ lists_ parent_ updated - RFC 8620 §5.1: “If the data changes, this string MUST change.”
Creating a reply to A raises A’s
replyCountfrom 1 to 2 (L638-639), soMessage/changeslists A as updated and the reply as created. - reply_
destroy_ lists_ parent_ updated - RFC 8620 §5.1: “If the data changes, this string MUST change.”
Destroying B, the only reply to A, lowers A’s
replyCountfrom 1 to 0, soMessage/changeslists A as updated and B as destroyed. - run
- Run
testto completion on a fresh multi-thread tokio runtime with four workers, so the concurrency tests race on real threads. - sender_
expires_ at_ hard_ deletes_ at_ deadline - L747 (jmap-chat-spec 77c3474), §Message
senderExpiresAt: “servers SHOULD permanently delete this message — removing the row entirely, not leaving a tombstone — at or before this time. A hard-deleted message appears in thedestroyedlist of subsequentMessage/changesresponses, notupdated.” - space_
destroy_ destroys_ channel_ read_ positions - Destroying a Space destroys its channel Chats (§Destroying a Space),
so their
ReadPositions go too (L993). - space_
join_ creates_ read_ positions_ for_ its_ channels - L993: “For channel Chats, a
ReadPositionis created when the owner joins the containing Space.” Only that Space’s channels get one. - space_
query_ filters_ name_ substring - L1389 (jmap-chat-spec 33702a5) §Space/query: “Filter properties:
name(String, substring match),isPublic(Boolean).” - space_
query_ sort_ ascending_ orders_ by_ property - RFC 8620 §5.5 Comparator
isAscending: “If true, sort in ascending order.” The Spaces are created out of name order so creation order cannot satisfy the assertion. - space_
query_ sort_ descending_ reverses_ order - RFC 8620 §5.5 Comparator
isAscending: “If false, reverse the comparator’s results to sort in descending order.” - state_
advances_ after_ create - Oracle: state advances after a successful
create_objectcall. - top_
level_ object_ value_ replaces_ property - Oracle: RFC 8620 §5.3: “Anything else: The value to set for this
property (this may be a replacement or addition to the object being
patched).” A top-level
deliveryReceiptsvalue replaces the whole property; the existingu1entry is not merged into it. - unread_
count_ in_ full_ get - aa01dd7 L635:
unreadCountis computed for a fullChat/get(noids) as well. - unread_
reply_ count_ without_ read_ position - L641-642 (jmap-chat-spec 91672c9) with no
lastReadMessageId: no reply has been read, so the unread count equals the reply count (ROOT: A and C -> 2).