LogoVersia Protocol

Instance Messaging Extension

Misconfigured or buggy instances often have trouble federating with others. This extension enables instances to send simple federation debug messages.

This extension is intended to help developers debug federation issues between instances. It is not intended for general-purpose messaging.

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 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.

Instance Metadata Extensions

This extension adds the following metadata to instances:

  • Name
    endpoint
    Required
    Required
    Type
    string
    Description

    The endpoint to send federation debug messages to.

    Sending Messages

    To send a federation debug message, instances should make a POST request to the appropriate endpoint with a simple text body containing a helpful message.

    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:

    Unhelpful Message

    Federation failed.

Example Instance Metadata

{
    "type": "InstanceMetadata",
    "name": "Jane.org",
    "software": {
        "name": "Versia Server",
        "version": "0.7.0"
    },
    "compatibility": {
        "versions": [
            "0.4.0"
        ],
        "extensions": [
            "pub.versia:reactions",
            "pub.versia:polls",
            "pub.versia:reports",
            "pub.versia:instance_messaging"
        ]
    },
    "host": "jane.org",
    "created_at": "2021-07-01T00:00:00Z",
    "extensions": { 
        "pub.versia:instance_messaging": {
            "endpoint": "https://jane.org/api/reports",
        },
    }
}