#Assistants

The assistants feature allows a Bibliogram instance to contact another server (the "assistant") for help fetching a user if the original server is blocked.

The assistant can be run standalone, or it can be run in combination with the Bibliogram frontend.

#Running the assistant

In your config file, set as_assistant/enabled to true to enable the assistant on the Bibliogram frontend. You can run the assistant standalone with npm run assistant, which bypasses this setting.

To prevent abuse, the assistant can ask for authentication keys before answering requests. To use this, set as_assistant/require_key to true, then add keys as strings to the as_assistant/keys array.

A complete section of the config might look like this:

as_assistant: {
    enabled: true,
    require_key: true,
    keys: [
        "this is very secret",
        "this is also secret"
    ]
}

Only one of the keys must be supplied for access, so generate one key per person that wants access. You can then revoke a single key if you later decide you don't trust that person without affecting the other people.

#Using other assistants

In your config file, set use_assistant/enabled to true, then add assistants to the use_assistant/assistants array. An example might look like this:

use_assistant: {
    enabled: true,
    assistants: [
        {
            origin: "https://example.com",
            key: "this is very secret"
        }
    ]
}

If the assistant does not require a key, set the key field to null.

Your server will then contact all the assistants that you add for help.

#Switching

The server initially contacts one assistant for each request, but falls back to others if the first one fails for whatever reason. If all assistants fail, the frontend will say 503 Blocked as if assistants hadn't been tried at all.

The server tries assistants in order of least recently accessed, to politely rotate through them without overloading one.

If an assistant reports that it is blocked itself, it won't be tried again for 2 hours. This timer can be adjusted with use_assistant/blocked_request_cooldown, which is a number in milliseconds.

If an assistant isn't accessible for network reasons, it won't be tried again for 20 minutes. This timer is also adjustable with use_assistant/offline_request_cooldown, which is also a number in milliseconds.

Both of these cooldown values apply to all assistants. If your assistant is a server that is perhaps already blocked, like bibliogram.art, consider setting blocked_request_cooldown to 1 to disable the cooldown. If your assistant is a server that only acts as an assistant, you should keep the default cooldown value to allow it to try to recover if it does get blocked.

#Recursing?

If a server is responding to an assistant request, it won't try to call its own assistants. First it tries to fetch from its own database. If it doesn't have the user stored, it'll request the page from Instagram. If that fails, then it's done, no more fallbacks.

If assistants recursed, this could lead to infinite loops of assistants calling each other, which would be really funny but also really bad.

#Caching

When acting as an assistant:

• If the incoming request is for a cached user, the cache will be served instead of making an outgoing request.
• If an outgoing request is made, the result will be cached.

When using assistants:

• The result of successful requests will be cached.