{"id":18704555,"url":"https://github.com/ocalasans/samp-query-node","last_synced_at":"2025-11-09T04:30:34.546Z","repository":{"id":260835572,"uuid":"881493381","full_name":"ocalasans/samp-query-node","owner":"ocalasans","description":"JavaScript API for making requests and extracting data from SA-MP (San Andreas Multiplayer) servers, designed to run in a Node.js environment.","archived":false,"fork":false,"pushed_at":"2025-01-21T01:51:06.000Z","size":59,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-21T02:29:52.082Z","etag":null,"topics":["api","javascript","js","networking","node","node-js","nodejs","nodejs-api","nodejs-modules","query","sa-mp","sa-mp-development","samp","server","server-query","server-status"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ocalasans.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-31T17:22:17.000Z","updated_at":"2025-01-21T01:51:09.000Z","dependencies_parsed_at":"2024-11-02T23:19:12.348Z","dependency_job_id":null,"html_url":"https://github.com/ocalasans/samp-query-node","commit_stats":null,"previous_names":["ocalasans/samp-query-node"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocalasans%2Fsamp-query-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocalasans%2Fsamp-query-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocalasans%2Fsamp-query-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocalasans%2Fsamp-query-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ocalasans","download_url":"https://codeload.github.com/ocalasans/samp-query-node/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239567361,"owners_count":19660467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","javascript","js","networking","node","node-js","nodejs","nodejs-api","nodejs-modules","query","sa-mp","sa-mp-development","samp","server","server-query","server-status"],"created_at":"2024-11-07T12:07:16.652Z","updated_at":"2025-02-18T23:25:35.548Z","avatar_url":"https://github.com/ocalasans.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# samp-query-node\n\nUma API completa para ambientes **Node.js**, projetada para consultas a servidores SA-MP (San Andreas Multiplayer) e compatível com o OPEN.MP (Open Multiplayer). Oferece recursos avançados de monitoramento e coleta de informações em tempo real.\n\n### Idiomas\n\n- Deutsch: [README](translations/Deutsch/README.md)\n- English: [README](translations/English/README.md)\n- Español: [README](translations/Espanol/README.md)\n- Français: [README](translations/Francais/README.md)\n- Italiano: [README](translations/Italiano/README.md)\n- Polski: [README](translations/Polski/README.md)\n- Русский: [README](translations/Русский/README.md)\n- Svenska: [README](translations/Svenska/README.md)\n- Türkçe: [README](translations/Turkce/README.md)\n\n## Índice\n\n- [samp-query-node](#samp-query-node)\n    - [Idiomas](#idiomas)\n  - [Índice](#índice)\n  - [Sobre a API](#sobre-a-api)\n  - [Instalação](#instalação)\n  - [Funcionalidades](#funcionalidades)\n    - [Sistema de Consulta Principal](#sistema-de-consulta-principal)\n  - [Estrutura da API](#estrutura-da-api)\n    - [Classes Principais](#classes-principais)\n      - [1. DNS\\_Cache](#1-dns_cache)\n      - [2. Query\\_Manager](#2-query_manager)\n      - [3. SAMP\\_Strings](#3-samp_strings)\n  - [Sistema de Cache DNS](#sistema-de-cache-dns)\n  - [Sistema de Latência](#sistema-de-latência)\n    - [Medição de Ping](#medição-de-ping)\n    - [Exemplos de Uso](#exemplos-de-uso)\n      - [1. Consulta Básica](#1-consulta-básica)\n      - [2. Consulta com Opções Personalizadas](#2-consulta-com-opções-personalizadas)\n      - [3. Utilizando Promises](#3-utilizando-promises)\n      - [4. Monitoramento Contínuo](#4-monitoramento-contínuo)\n  - [Tratamento de Erros](#tratamento-de-erros)\n    - [1. Erros de Conexão](#1-erros-de-conexão)\n    - [2. Timeouts](#2-timeouts)\n    - [3. Validação de Dados](#3-validação-de-dados)\n  - [Considerações de Desempenho](#considerações-de-desempenho)\n    - [Otimizações Implementadas](#otimizações-implementadas)\n  - [Limitações Técnicas](#limitações-técnicas)\n  - [Estrutura de Resposta](#estrutura-de-resposta)\n  - [Licença](#licença)\n    - [Condições:](#condições)\n\n## Sobre a API\n\nO **SA-MP Query Node** é uma API desenvolvida especificamente para interagir com servidores SA-MP, permitindo a coleta de informações detalhadas sobre o servidor em tempo real. A API utiliza o protocolo de consulta nativo do SA-MP e implementa várias camadas de otimização para garantir consultas eficientes e confiáveis.\n\nA API foi projetada com foco em:\n- Confiabilidade nas consultas\n- Eficiência no processamento\n- Facilidade de uso\n- Tratamento robusto de erros\n- Suporte completo a todas as funcionalidades do protocolo SA-MP\n\n## Instalação\n\nClone o repositório para sua máquina local:\n\n```bash\ngit clone https://github.com/ocalasans/samp-query-node.git\n```\n\n## Funcionalidades\n\n### Sistema de Consulta Principal\n\nA API oferece um sistema de consulta completo que permite obter:\n\n1. **Informações Básicas do Servidor:**\n   - Nome do servidor\n   - Modo de jogo atual\n   - Idioma configurado\n   - Status de proteção por senha\n   - Número máximo de jogadores\n   - Número atual de jogadores online\n\n2. **Lista Detalhada de Jogadores:**\n   - ID do jogador\n   - Nome do jogador\n   - Pontuação atual\n   - Latência (ping) do jogador\n\n3. **Regras do Servidor:**\n   - Configurações de lag compensation\n   - Clima atual\n   - Outras regras personalizadas definidas pelo servidor\n\n4. **Medições de Desempenho:**\n   - Latência do servidor (ping)\n   - Tempo de resposta das consultas\n   - Estatísticas de conexão\n\n## Estrutura da API\n\n### Classes Principais\n\n#### 1. DNS_Cache\n\n```javascript\nclass DNS_Cache {\n    constructor() {\n        this.cache = new Map();\n        this.Resolve_DNS = promisify(dns.resolve4);\n    }\n}\n```\n\nA classe **DNS_Cache** é responsável por:\n- Armazenar temporariamente resoluções DNS\n- Otimizar consultas repetidas\n- Reduzir a latência de conexão\n- Gerenciar o tempo de vida do cache\n\nMétodos principais:\n- `Get_IP_Address(host_name)`: Resolve e cache endereços IP\n- Cache automático com duração configurável (padrão: 5 minutos)\n- Fallback para hostname em caso de falha na resolução\n\n#### 2. Query_Manager\n\n```javascript\nclass Query_Manager extends EventEmitter {\n    constructor() {\n        super();\n        this.Active_Queries = new Map();\n    }\n}\n```\n\nO **Query_Manager** controla:\n- Gerenciamento de consultas ativas\n- Timeouts e retentativas\n- Eventos de conclusão de consulta\n- Limpeza de consultas expiradas\n\nFuncionalidades:\n- Sistema de retry automático\n- Controle de tempo limite\n- Gerenciamento de múltiplas consultas simultâneas\n- Emissão de eventos de conclusão\n\n#### 3. SAMP_Strings\n\n```javascript\nclass SAMP_Strings {\n    static charset = [/* conjunto de caracteres SA-MP */];\n    static Decode_String(buffer_data) { /* ... */ }\n}\n```\n\nResponsável por:\n- Decodificação de strings do SA-MP\n- Suporte a caracteres especiais\n- Limpeza e sanitização de strings\n- Conversão de buffers para texto\n\n## Sistema de Cache DNS\n\nO sistema de cache DNS é uma parte crucial da API, implementando:\n\n1. **Gerenciamento de Cache:**\n   - Armazenamento eficiente de resoluções DNS\n   - Verificação de validade temporal\n   - Limpeza automática de entradas antigas\n\n2. **Otimização de Desempenho:**\n   - Redução de consultas DNS redundantes\n   - Melhoria no tempo de resposta\n   - Economia de recursos de rede\n\n3. **Configurações de Cache:**\n   ```javascript\n   const DNS_CACHE_TIME = 300000; // 5 minutos\n   ```\n\n4. **Tratamento de Falhas:**\n   - Fallback para hostname original\n   - Retry automático em falhas temporárias\n   - Logging de erros de resolução\n\n## Sistema de Latência\n\n### Medição de Ping\n\nO sistema de medição de latência implementa:\n\n1. **Coleta de Amostras:**\n   ```javascript\n   const LATENCY = {\n       SAMPLES: 5,\n       CHECK_INTERVAL: 50,\n       TIMEOUT: 2000,\n       MAX_VALID_PING: 800\n   };\n   ```\n\n2. **Processamento de Resultados:**\n   - Cálculo de média de latência\n   - Filtragem de valores atípicos\n   - Detecção de timeouts\n\n3. **Otimizações:**\n   - Múltiplas amostras para precisão\n   - Intervalos configuráveis\n   - Timeouts independentes\n\n### Exemplos de Uso\n\n#### 1. Consulta Básica\n\n```javascript\nconst query = require('samp-query-node');\n\nquery('127.0.0.1:7777', (erro, resposta) =\u003e {\n    if (erro) {\n        console.error('Erro na consulta:', erro);\n        return;\n    }\n    \n    console.log('Informações do servidor:', resposta);\n});\n```\n\n#### 2. Consulta com Opções Personalizadas\n\n```javascript\nconst opcoes = {\n    host: '127.0.0.1',\n    port: 7777,\n    timeout: 1500  // timeout de 1.5 segundos\n};\n\nquery(opcoes, (erro, resposta) =\u003e {\n    if (erro) {\n        console.error('Erro:', erro);\n        return;\n    }\n    \n    console.log('Nome do servidor:', resposta.hostname);\n    console.log('Jogadores:', resposta.onlinePlayers);\n    console.log('Modo de jogo:', resposta.gamemode);\n    \n    // Processando lista de jogadores\n    resposta.players.forEach(jogador =\u003e {\n        console.log(`${jogador.name}: ${jogador.score} pontos`);\n    });\n});\n```\n\n#### 3. Utilizando Promises\n\n```javascript\nconst util = require('util');\nconst Query_Async = util.promisify(query);\n\nasync function Requisitar_Servidor() {\n    try {\n        const info = await Query_Async('127.0.0.1:7777');\n        \n        console.log('Servidor:', info.hostname);\n        console.log('Jogadores:', info.onlinePlayers);\n        console.log('Ping:', info.ping, 'ms');\n        \n        // Processando regras do servidor\n        if (info.rules.lagcomp === 'On') {\n            console.log('Servidor com lag compensation ativado');\n        }\n        \n        // Listando top jogadores\n        const topJogadores = info.players\n            .sort((a, b) =\u003e b.score - a.score)\n            .slice(0, 5);\n            \n        console.log('\\nTop 5 Jogadores:');\n        topJogadores.forEach((jogador, index) =\u003e {\n            console.log(`${index + 1}. ${jogador.name}: ${jogador.score} pontos`);\n        });\n        \n    } catch (erro) {\n        console.error('Erro ao consultar servidor:', erro);\n    }\n}\n```\n\n#### 4. Monitoramento Contínuo\n\n```javascript\nasync function Monitorar_Servidor(endereco, intervalo = 60000) {\n    const Query_Async = util.promisify(query);\n    \n    console.log(`Iniciando monitoramento de ${endereco}`);\n    \n    setInterval(async () =\u003e {\n        try {\n            const info = await Query_Async(endereco);\n            \n            console.log('\\n=== Status do Servidor ===');\n            console.log(`Tempo: ${new Date().toLocaleString()}`);\n            console.log(`Jogadores: ${info.onlinePlayers}/${info.maxPlayers}`);\n            console.log(`Ping: ${info.ping}ms`);\n            console.log(`Modo: ${info.gamemode}`);\n            \n            if (info.onlinePlayers \u003e 0) {\n                console.log('\\nJogadores Online:');\n                info.players.forEach(jogador =\u003e {\n                    console.log(`- ${jogador.name} (Ping: ${jogador.ping}ms)`);\n                });\n            }\n            \n        } catch (erro) {\n            console.error('Erro no monitoramento:', erro);\n        }\n    }, intervalo);\n}\n```\n\n## Tratamento de Erros\n\nA API implementa um sistema robusto de tratamento de erros:\n\n### 1. Erros de Conexão\n\n```javascript\nquery('127.0.0.1:7777', (erro, resposta) =\u003e {\n    if (!resposta.hostname) {\n        console.log('Servidor offline ou inacessível');\n    }\n});\n```\n\n### 2. Timeouts\n\n```javascript\nconst opcoes = {\n    host: '127.0.0.1',\n    port: 7777,\n    timeout: 2000  // 2 segundos\n};\n\nquery(opcoes, (erro, resposta) =\u003e {\n    if (erro) {\n        console.log('Servidor não respondeu no tempo limite');\n    }\n});\n```\n\n### 3. Validação de Dados\n\n```javascript\nquery('127.0.0.1:7777', (erro, resposta) =\u003e {\n    // Verificações de segurança\n    if (resposta.onlinePlayers \u003e resposta.maxPlayers) {\n        console.log('Dados inconsistentes recebidos');\n        return;\n    }\n    \n    // Validação de jogadores\n    resposta.players = resposta.players.filter(jogador =\u003e {\n        return jogador.name \u0026\u0026 jogador.score \u003e= 0 \u0026\u0026 jogador.ping \u003e= 0;\n    });\n});\n```\n\n## Considerações de Desempenho\n\n### Otimizações Implementadas\n\n1. **Cache DNS:**\n   - Reduz consultas DNS repetidas\n   - Cache com tempo de vida configurável\n   - Limpeza automática de cache\n\n2. **Gerenciamento de Conexões:**\n   - Reutilização de sockets quando possível\n   - Timeouts otimizados\n   - Sistema de retry inteligente\n\n3. **Processamento de Dados:**\n   - Parsing eficiente de pacotes\n   - Validação otimizada de dados\n   - Gerenciamento de memória eficiente\n\n4. **Medição de Latência:**\n   - Múltiplas amostras para precisão\n   - Filtro de valores atípicos\n   - Cálculo otimizado de médias\n\n## Limitações Técnicas\n\n1. **Limitações de Protocolo:**\n   - Tamanho máximo de pacote: 2048 bytes\n   - Máximo de jogadores consultáveis: 100\n   - Timeout padrão: 1000ms\n\n2. **Limitações de Cache:**\n   - Tempo máximo de cache DNS: 5 minutos\n   - Limite de entradas no cache\n\n3. **Limitações de Rede:**\n   - Máximo de 3 tentativas por consulta\n   - Intervalo mínimo entre tentativas: 150ms\n   - Ping máximo válido: 800ms\n\n4. **Limitações de Dados:**\n   - Tamanho máximo de strings\n   - Número máximo de regras do servidor\n   - Limitações de caracteres especiais\n\n## Estrutura de Resposta\n\nA API retorna um objeto detalhado com todas as informações do servidor:\n\n```javascript\n{\n    // Informações básicas\n    address: \"127.0.0.1\", // Endereço do servidor\n    port: 7777, // Porta do servidor\n    hostname: \"Server\", // Nome do servidor\n    gamemode: \"RolePlay\", // Modo de jogo\n    language: \"Português - Brasil\", // Idioma\n    \n    // Status do servidor\n    password: false, // Proteção por senha\n    maxPlayers: 100, // Máximo de jogadores\n    onlinePlayers: 45, // Jogadores online\n    ping: 58, // Latência em ms\n    queryTime: 1635789012345, // Timestamp da consulta\n    \n    // Lista de jogadores\n    players: [\n        {\n            id: 0, // ID do jogador\n            name: \"Calasans\", // Nome\n            score: 63, // Pontuação\n            ping: 117 // Ping do jogador\n        },\n    ],\n    \n    // Regras do servidor\n    rules: {\n        allowed_clients: \"0.3.7, 0.3.DL\", // Versões permitidas de clientes\n        artwork: 1, // Habilitação de artwork\n        lagcomp: \"On\", // Status do lag comp\n        mapname: \"San Andreas\", // Nome do mapa\n        version: \"0.3.7\", // Versão do servidor\n        weather: 10, // ID do clima\n        weburl: \"website.com\", // URL do site do servidor\n        worldtime: \"12:00\" // Hora do mundo no servidor\n    }\n}\n```\n\n## Licença\n\nEsta API está protegido sob a Licença MIT, que permite:\n- ✔️ Uso comercial e privado\n- ✔️ Modificação do código fonte\n- ✔️ Distribuição do código\n- ✔️ Sublicenciamento\n\n### Condições:\n\n- Manter o aviso de direitos autorais\n- Incluir cópia da licença MIT\n\nPara mais detalhes sobre a licença: https://opensource.org/licenses/MIT\n\n**Copyright (c) Calasans - Todos os direitos reservados**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focalasans%2Fsamp-query-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Focalasans%2Fsamp-query-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focalasans%2Fsamp-query-node/lists"}