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