Skip to content

features

Puxada de membros

Puxe membros verificados para um novo servidor com atribuição automática de função. Entenda como os tokens OAuth2 permitem o pull, os limites de taxa, os cooldowns, os filtros, o mapeamento de funções e o pull worker.

Visão geral

A extração de membros é o processo de adicionar membros que verificaram por meio de um de seus servidores a um servidor diferente. Quando os membros fazem a verificação por meio do Restore Hub, eles concedem o escopo OAuth2 guilds.join, que autoriza o Restore Hub a adicioná-los a qualquer servidor em que você tenha um bot. O pulling usa esses tokens armazenados para adicionar membros ao seu servidor de destino e atribuir uma função.

Esse é um modelo de consentimento único: o membro autoriza durante a verificação e pode revogar o acesso a qualquer momento por meio das configurações de aplicativos autorizados do Discord. O Restore Hub não solicita novamente o consentimento.

Como os tokens OAuth2 permitem o pulling

Quando um membro conclui a verificação, o Restore Hub armazena o token de acesso OAuth2 e o token de atualização (ambos criptografados com AES-256). O token de acesso é válido por 7 dias. O token de atualização é válido por 30 dias.

Quando um trabalho de extração é executado, o Restore Hub usa o escopo guilds.join com o token de acesso do membro para adicioná-lo ao servidor de destino por meio do ponto de extremidade PUT /guilds/{guild_id}/members/{user_id} do Discord. Esse ponto de extremidade também aceita uma matriz de funções, permitindo a atribuição imediata de funções ao ingressar.

Se o token de acesso tiver expirado, o Restore Hub o atualizará automaticamente usando o token de atualização antes de tentar a extração. Se o token de atualização também tiver expirado (o membro não reverificou em 30 dias) ou se o membro tiver revogado o acesso, o membro será marcado como "não extraível".

Mecanismo de atualização de token

O Restore Hub atualiza proativamente os tokens 5 minutos antes de expirarem (TOKEN_REFRESH_BUFFER_MS = 5 minutos). Durante um trabalho de extração, se um token estiver a menos de 5 minutos da expiração, o Restore Hub o atualiza antes de usá-lo.

Quando uma atualização é bem-sucedida, o novo token de acesso, o token de atualização e o registro de data e hora de expiração são salvos (criptografados) no banco de dados. Quando uma atualização falha (acesso revogado pelo usuário, token expirado além da renovação, erro da API do Discord), o sinalizador isPullable do membro é definido como falso.

Dica: Os membros podem recuperar o status de "extraível" fazendo uma reverificação. Os novos tokens OAuth2 substituem os antigos.

O que significa "extraível"?

Um membro é marcado como "extraível" (isPullable = true) quando tem tokens OAuth2 válidos e não expirados. Um membro se torna "não extraível" quando:

  • O token de acesso expirou E o token de atualização também expirou (nenhuma reverificação em cerca de 30 dias)
  • Eles revogaram o acesso do Restore Hub em Configurações do Discord → Aplicativos autorizados
  • Uma tentativa de atualização de token falhou devido a um erro da API do Discord
  • Eles foram marcados manualmente como não extraíveis pelo proprietário do servidor

Iniciando um pull

Você pode iniciar um pull de três lugares: o painel, um comando de barra do Discord ou a API REST.

  1. No painel de controle - Navegue até seu servidor de origem → Membros → Pull Members. Selecione o servidor de destino, defina opcionalmente uma função, um limite e filtros e, em seguida, clique em "Start Pull" (Iniciar extração).
  2. Do Discord (Premium+) - Use o comando /pull em seu servidor de origem. Especifique o ID do servidor de destino e a função opcional.
  3. Por meio da API - POST /api/v1/servers/:id/pull com um corpo JSON especificando targetGuildId, roleId, limit, preserveRoles, roleMapping e filter.
POST /api/v1/servers/:id/pull
{
  "targetGuildId": "123456789012345678",
  "roleId": "987654321098765432",
  "limit": 500,
  "preserveRoles": false,
  "roleMapping": {
    "111111111111111111": "222222222222222222"
  },
  "filter" (filtro): {
    "roleIds": ["333333333333333333"],
    "memberIds": ["444444444444444444"]
  }
}

Limitação de taxa

A API do Discord tem limites rígidos de taxa no ponto de extremidade PUT /guilds/{guild_id}/members/{user_id}. O Restore Hub processa membros a aproximadamente 50 por minuto (PULL_RATE_LIMIT = 50) para permanecer com segurança dentro dos limites do Discord.

Isso significa que uma extração de 1.000 membros leva aproximadamente 20 minutos. Um pull de 5.000 membros leva aproximadamente 100 minutos. O pull worker gerencia o tempo automaticamente - você não precisa se preocupar em atingir os limites de taxa do Discord.

Aviso: Exceder os limites de taxa do Discord pode resultar no banimento temporário ou permanente de seu bot. A limitação de taxa integrada do Restore Hub evita isso, mas esteja ciente de que grandes extrações levam tempo.

Recargas por plano

Para evitar abusos, cada plano tem um período de resfriamento entre os pulls para o mesmo servidor de origem:

| Plano de resfriamento entre as puxadas
|---|---|
| Grátis | 6 horas |
| Premium | 1 hora |
| Business | 15 minutos |
| Enterprise | Sem tempo de espera |

Dica: o tempo de espera é por servidor de origem, não global. Se você tiver dois servidores de origem, poderá extrair de ambos simultaneamente, mesmo no plano Free.

Mapeamento de funções

Ao extrair membros, você pode opcionalmente mapear funções do servidor de origem para funções no servidor de destino. Isso é útil quando você deseja preservar as funções dos membros em todos os servidores.

O campo roleMapping é um objeto JSON em que as chaves são IDs de função do servidor de origem e os valores são IDs de função no servidor de destino. Quando um membro é puxado, o Restore Hub procura suas funções no servidor de origem e atribui as funções mapeadas correspondentes no destino.

Se preserveRoles for definido como true sem um roleMapping, o Restore Hub tentará corresponder as funções por nome. As funções com nomes idênticos em ambos os servidores são mapeadas automaticamente.

Filtros de puxar

Você pode restringir os membros que estão incluídos em um pull usando filtros:

filtro | Descrição | Filtro | Descrição
|---|---|
| Somente extrair membros que tenham pelo menos uma das funções especificadas no servidor de origem
| memberIds | Extrair apenas membros específicos por seus IDs de usuário do Discord
| Número máximo de membros a serem extraídos (por exemplo, 500). Se não for definido, todos os membros extraíveis serão incluídos

Status do trabalho pull

Cada trabalho de extração passa por uma série de status. Você pode monitorar o progresso no painel ou via GET /api/v1/pulls/:id.

| Status | Significado |
|---|---|
| PENDING | Trabalho criado, aguardando para ser enfileirado
| QUEUED | Trabalho adicionado à fila de trabalho, aguardando que um trabalhador o pegue
| RUNNING | O trabalhador está processando ativamente os membros (pulledCount aumenta em tempo real)
| COMPLETED | Todos os membros processados (alguns podem ter falhado ou sido ignorados)
| FAILED | O trabalho inteiro falhou devido a um erro crítico (por exemplo, bot removido do servidor de destino)
| CANCELLED | O trabalho foi cancelado pelo usuário antes da conclusão

Contadores de trabalhos de puxar

Durante e após um pull, os seguintes contadores monitoram o progresso:

  • totalMembers - O número total de membros que serão processados (com base nos filtros e no limite).
  • pulledCount - Número de membros adicionados com sucesso ao servidor de destino.
  • failedCount - Número de membros que não puderam ser extraídos (token expirado, acesso revogado pelo usuário, erro de API do Discord).
  • skippedCount - Número de membros ignorados (já no servidor de destino, banidos do servidor de destino, etc.).
  • progresso - Calculado como (pulledCount + failedCount + skippedCount) / totalMembers * 100.

O trabalhador que puxa

Os trabalhos pull são processados por um trabalhador em segundo plano (fila de trabalhos BullMQ). O trabalhador:

  • Retira da fila o próximo pull job pendente.
  • Carrega todos os membros extraíveis do servidor de origem (aplicando filtros).
  • Para cada membro: verifica se o token é válido, atualiza se necessário, chama a API do Discord para adicioná-lo ao servidor de destino com a(s) função(ões) especificada(s) e atualiza os contadores.
  • Respeita o limite de taxa de 50 minutos, espaçando as chamadas de API.
  • Trata os erros com elegância - se um único membro falhar, o trabalho continua com o próximo membro.
  • Atualiza o status do trabalho para COMPLETED ou FAILED quando concluído.
  • Registra todos os erros no campo errorLog JSON para depuração.

O que acontece quando os tokens expiram

Se o token de acesso de um membro expirou, mas seu token de atualização ainda é válido, o trabalhador atualiza automaticamente o token e tenta novamente. Se o token de atualização também tiver expirado ou sido revogado, o membro será marcado como não extraível (isPullable = false) e contado em failedCount.

Para minimizar os problemas de expiração de tokens, incentive os membros a reverificarem periodicamente ou configure alertas para monitorar sua porcentagem de membros extraíveis.

Multi-Server Pull (Enterprise)

No plano Enterprise, você pode puxar membros de vários servidores de origem para um único servidor de destino em uma única operação. Isso é útil para a consolidação de comunidades. O pull de vários servidores respeita os limites de taxa individuais e processa os membros de cada servidor de origem sequencialmente.

Extração automática de alertas (Business+)

Na versão Business e superior, você pode configurar alertas (nuke, raid, exclusão) para acionar automaticamente um pull para um servidor de backup. Se o seu servidor for comprometido, o Restore Hub poderá começar a puxar automaticamente os membros verificados para um servidor seguro sem intervenção manual.

Puxada de membros — Restore Hub Docs | Restore Hub