mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 22:38:19 +01:00
43 lines
1.8 KiB
Plaintext
43 lines
1.8 KiB
Plaintext
export const metadata = {
|
|
title: "Instance Messaging Extension",
|
|
description: "Instance Messaging allows instances to send federation debug messages."
|
|
}
|
|
|
|
# Instance Messaging Extension
|
|
|
|
Misconfigured or buggy instances often have trouble federating with others. This extension enables instances to send simple federation debug messages. {{ className: "lead" }}
|
|
|
|
<Note>
|
|
This extension is intended to help developers debug federation issues between instances. It is not intended for general-purpose messaging.
|
|
</Note>
|
|
|
|
## Purpose
|
|
|
|
Often, federation "fails silently" with no indication of what went wrong, as instances are incapable of communicating with each other outside of administrators manually checking logs.
|
|
|
|
For example, let's consider the following scenario:
|
|
1. `joe.social` and `jane.org` are two instances.
|
|
2. `joe.social` tries to fetch a user profile from `jane.org`, at `jane.org/users/nkGEd8eI98` for example.
|
|
3. `jane.org` responds with a [User](/entities/user) object with a missing or incorrect field, such as an improperly validated `username`.
|
|
4. `joe.social` is incapable of processing the response and silently fails to fetch the user profile.
|
|
|
|
In this scenario, `jane.org` has no way of knowing what went wrong, as `joe.social` does not provide any feedback.
|
|
|
|
|
|
## Sending Messages
|
|
|
|
To send a federation debug message, instances **should** make a `POST` request to the `/.versia/v0.6/messaging` endpoint with a simple text body containing a helpful message.
|
|
|
|
No signatures are required (either on the request or response), and no response body is expected.
|
|
|
|
```text {{ "title": "Helpful Message" }}
|
|
Validation failed for https://jane.org/users/nkGEd8eI98.
|
|
Reasons:
|
|
- `username` must be alphanumeric. Found invalid character `@`.
|
|
```
|
|
|
|
Do not send useless messages, such as:
|
|
|
|
```text {{ "title": "Unhelpful Message" }}
|
|
Federation failed.
|
|
``` |