1
 2A Ping extension for ActivityPub
 3
 4This is merely a draft.
 5
 6-- rationale
 7
 8Diagnosing communication failures between federated servers often requires
 9sending test messages. There is no dedicated activity type for this purpose,
10however, and thus many operators use normal notes. This creates unnecessary
11noise. It would be better to have a side effect free message that can be
12triggered and sent on demand.
13
14The proposed Ping and corresponding Pong activities are similar to the ICMP
15echo request and echo reply messages. (c.f. the familiar ping tool.)
16
17Other online social contexts often use the term ping to refer to a variety
18of activities. The activity here is unrelated to any user visible activity or
19action.
20
21-- message format
22
23The ping message has a type of Ping. Here, user pinger on server
24h1.example.com is sending a Ping to testrcpt on h2.example.com.
25
26{
27	"@context": "https://www.w3.org/ns/activitystreams",
28	"type": "Ping",
29	"id": "https://h1.example.com/u/pinger/ping/r4nd0m1d",
30	"actor": "https://h1.example.com/u/pinger",
31	"to": "https://h2.example.com/u/testrcpt"
32}
33
34The Pong message is similar, but includes an object field quoting the Ping id
35field.
36
37{
38	"@context": "https://www.w3.org/ns/activitystreams",
39	"type": "Pong",
40	"id": "https://h2.example.com/u/testrcpt/pong/0pp0s1t3",
41	"actor": "https://h2.example.com/u/testrcpt",
42	"to": "https://h1.example.com/u/pinger",
43	"object": "https://h1.example.com/u/pinger/ping/r4nd0m1d"
44}
45
46Ping and Pong id fields look like URLs, but need not be fetchable. They are
47only intended as transient messages.
48
49-- semantics
50
51The Ping message should be sent from one actor to another, delivered to their
52inbox. Upon receipt of a Ping message, a server should reply with a Pong
53message. The Pong reply should quote the id of the Ping (just the id, not the
54whole message) in the object field.
55
56Random ids may used. They should be probabilistically unique.
57
58The usual access and verification checks performed for other messages should
59be performed for Ping and Pong as well. (If HTTP signatures are in use,
60messages should be signed by senders and verified by receivers.)
61
62Ping and Pong messages should be queued using the normal facilities. (Don't
63fast track.) Messages should not be retried. After one failure, drop the
64message.
65
66As these messages are intended as administrator aids, they should not be
67displayed to end users. They should not cause any lasting change in the state
68of either the sending or receiving server.
69
70Rate limiting and abuse controls apply as usual. Servers may choose to impose
71length restrictions on maximum id length. A minimum of 256 bytes should be
72supported.
73
74Servers which do not understand the Ping activity will hopefully ignore it.
75
76-- usage
77
78It is unspecified how one initiates a ping, but it is expected to be a manual
79operation performed by a system administrator. This will generate traffic,
80which may then be logged. The admin reads the logs and solves the problem.
81Specific problem solving instructions are not provided here.
82
83-- future
84
85It may be helpful to have a variant of Ping that does perform retries to test
86recovery after disconnect.