Testando Extensões Dependentes de Rede

Algumas extensões precisam se comunicar com um servidor HTTP externo ou outro listener de rede durante os testes (por exemplo, uma extensão que faz requisições HTTP de saída precisa de um servidor de echo local para recebê-las). Esta página aborda como estruturar esses testes para que sejam executados de forma confiável sob --parallel=auto e em diferentes sistemas operacionais. Os padrões apresentados aqui se aplicam igualmente a extensões em C++ e Rust, pois ambos usam o MTR como executor de testes, que as extensões em Rust executam por meio de cargo vsql test.

Por que portas fixas falham

Dois modos de falha tornam as portas fixas não confiáveis no MTR: Conflitos de porta sob --parallel. O MTR atribui a cada worker uma faixa de portas em torno do seu valor @@port. Uma porta fixa fora dessa faixa (digamos, 18777) pode colidir com o bloco reservado de outro worker ou com um serviço do sistema, o que causa EADDRINUSE intermitente que só se reproduz em alto paralelismo. Mudanças no nível do sistema operacional. Novas imagens de runner e versões de sistema operacional periodicamente reservam ou restringem portas que antes funcionavam. Uma porta que passa localmente e no CI hoje pode falhar silenciosamente ao vincular amanhã. A solução em ambos os casos é a mesma: vincule à porta 0 e deixe o sistema operacional atribuir uma porta disponível, depois comunique a porta real de volta ao teste.

Padrão A: Listener integrado ao servidor

Use este quando o listener de rede é executado dentro do processo do MySQL (por exemplo, uma extensão que incorpora um servidor HTTP). Na extensão, exponha a porta vinculada como uma variável de status após a vinculação:

// After calling bind() with port 0:
vsql_my_http_port = server.actual_port();  // exposed as vsql_my_ext.http_port

No teste, use o wait_condition.inc do MTR para consultar a variável de status até que ela seja diferente de zero, depois capture a porta em uma variável do MTR. Releia após qualquer ciclo de UNINSTALL EXTENSION / INSTALL EXTENSION, pois uma porta efêmera muda a cada vinculação.

--disable_query_log
let $wait_timeout= 10;
let $wait_condition=
  SELECT VARIABLE_VALUE > 0
  FROM performance_schema.global_status
  WHERE VARIABLE_NAME = 'vsql_my_ext.http_port';
--source include/wait_condition.inc
--let $my_port = `SELECT VARIABLE_VALUE FROM performance_schema.global_status WHERE VARIABLE_NAME = 'vsql_my_ext.http_port'`
--eval SET @url = CONCAT('http://127.0.0.1:', $my_port, '/endpoint');
--enable_query_log

SELECT my_extension.fetch(@url);

Padrão B: Listener em processo externo

Use este quando o listener é um processo independente — um servidor auxiliar em Python, uma API simulada ou qualquer programa externo que o MTR não controle diretamente.

Este padrão requer python3 no PATH. Os runners hospedados pelo GitHub o incluem; verifique a disponibilidade em runners auto-hospedados antes de usar.

O lançador em primeiro plano

Em vez de colocar o servidor em segundo plano com --exec ... & e consultar uma porta, use um script de lançamento em primeiro plano que:

Inicia o servidor em um subprocesso com start_new_session=True
Bloqueia até que o servidor tenha vinculado e escrito um arquivo de prontidão
Encerra, permitindo que o MTR continue

O MTR bloqueia em chamadas --exec em primeiro plano, então isso garante que o servidor esteja pronto antes que qualquer SQL seja executado, sem a necessidade de um poller ou sleep separado. launcher.py — escreva isto com --write_file:

import os, subprocess, sys, time

_dir = os.path.dirname(os.path.abspath(__file__))
port_inc = os.path.join(_dir, 'echo_port.inc')

# Drop a readiness file left by an aborted earlier run
try:
    os.remove(port_inc)
except OSError:
    pass

# Start the server subprocess detached from this process
proc = subprocess.Popen(
    [sys.executable, os.path.join(_dir, 'echo_server.py')],
    start_new_session=True,
    stdout=open(os.path.join(_dir, 'echo_server.log'), 'w'),
    stderr=subprocess.STDOUT,
)

# Write PID for cleanup
with open(os.path.join(_dir, 'echo_server.pid'), 'w') as f:
    f.write(str(proc.pid))

# Block until readiness file appears and is non-empty.
# Check content, not just existence — the file is created before the write
# completes and an empty read would produce a broken MTR include.
port_inc = os.path.join(_dir, 'echo_port.inc')
for _ in range(40):
    try:
        if open(port_inc).read().strip():
            sys.exit(0)
    except OSError:
        pass
    time.sleep(0.25)

# Timed out — print server log for diagnosis
with open(os.path.join(_dir, 'echo_server.log')) as f:
    sys.stderr.write(f.read())
sys.exit(1)

echo_server.py — o servidor em si, escrevendo sua porta antes de atender:

import http.server, json, os, signal, socketserver

signal.alarm(60)  # self-terminate if orphaned by a killed MTR job

class Handler(http.server.BaseHTTPRequestHandler):
    def handle_any(self):
        n = int(self.headers.get('Content-Length', 0))
        body = self.rfile.read(n).decode() if n else ''
        self.send_response(200)
        payload = json.dumps({'method': self.command, 'body': body}).encode()
        self.send_header('Content-Type', 'application/json')
        self.send_header('Content-Length', len(payload))
        self.end_headers()
        self.wfile.write(payload)
    do_GET = do_POST = do_PUT = do_DELETE = do_PATCH = handle_any
    def log_message(self, *args): pass

_dir = os.path.dirname(os.path.abspath(__file__))

# HTTPServer.server_bind() calls socket.getfqdn() -- a reverse-DNS lookup that
# can stall for minutes on a CI runner, before the bound port can be read.
# Override it to skip that lookup entirely.
class Server(http.server.HTTPServer):
    def server_bind(self):
        socketserver.TCPServer.server_bind(self)
        self.server_name = 'localhost'
        self.server_port = self.server_address[1]

srv = Server(('127.0.0.1', 0), Handler)
port = srv.server_address[1]

# Write atomically via rename — the launcher reads content, not just existence,
# so the file must be complete before it becomes visible.
tmp = os.path.join(_dir, 'echo_port.tmp')
inc = os.path.join(_dir, 'echo_port.inc')
with open(tmp, 'w') as f:
    f.write('let $echo_port = %d;\n' % port)
os.rename(tmp, inc)

srv.serve_forever()

No teste

Inicie o lançador (em primeiro plano, já que o MTR bloqueia até que ele encerre), depois inclua o arquivo de porta:

--write_file $MYSQLTEST_VARDIR/tmp/echo_server.py
# ... (echo_server.py contents)
EOF

--write_file $MYSQLTEST_VARDIR/tmp/launcher.py
# ... (launcher.py contents)
EOF

--exec python3 $MYSQLTEST_VARDIR/tmp/launcher.py
--disable_query_log
--source $MYSQLTEST_VARDIR/tmp/echo_port.inc
--eval SET @echo_url = CONCAT('http://127.0.0.1:', $echo_port, '/');
--enable_query_log

Mantendo a porta fora do arquivo de resultado

O arquivo de resultado registra o SQL conforme escrito. Se uma URL contiver o número da porta efêmera, o arquivo de resultado conteria um valor diferente a cada execução e o teste sempre falharia no registro/replay. Inclua o arquivo de porta e defina a variável de sessão do MySQL em conjunto sob --disable_query_log, para que nem a atribuição let nem a porta efêmera apareçam na saída. Use a variável de sessão em todos os lugares onde uma URL for necessária:

--disable_query_log
--source $MYSQLTEST_VARDIR/tmp/echo_port.inc
--eval SET @echo_url = CONCAT('http://127.0.0.1:', $echo_port, '/');
--enable_query_log

# All queries reference @echo_url — the port never appears in the result file
SELECT JSON_VALUE(CONVERT(my_ext.http_get(@echo_url) USING utf8mb4), '$.status') AS status;

Gerenciamento de processos

Registre a saída do auxiliar e nunca a descarte. O padrão de lançador acima escreve o stderr do servidor em echo_server.log e o imprime em caso de falha. Descartar a saída do auxiliar torna as instabilidades inexplicáveis nos artefatos do CI. Encerre por PID, não por nome. No Linux, pkill -f echo_server.py pode corresponder ao próprio processo do MTR via /proc/cmdline. Use o arquivo de PID escrito pelo lançador:

--exec sh -c 'kill `cat $MYSQLTEST_VARDIR/tmp/echo_server.pid` 2>/dev/null || true'

Remova todos os arquivos temporários antes de o teste terminar. O check-testcase do MTR sinaliza qualquer arquivo deixado em $MYSQLTEST_VARDIR/tmp/ como estado sujo e faz o teste falhar:

--remove_file $MYSQLTEST_VARDIR/tmp/echo_server.py
--remove_file $MYSQLTEST_VARDIR/tmp/launcher.py
--remove_file $MYSQLTEST_VARDIR/tmp/echo_server.log
--remove_file $MYSQLTEST_VARDIR/tmp/echo_server.pid
--remove_file $MYSQLTEST_VARDIR/tmp/echo_port.inc

O arquivo vsql-http/mysql-test/t/vsql_http_requests.test demonstra o mesmo objetivo — um processo auxiliar em segundo plano com um encerramento limpo e livre de condições de corrida — por meio de um mecanismo concreto diferente: um único arquivo Python que faz re-exec de si mesmo com uma flag --serve para se tornar o processo filho desanexado, em vez da divisão entre launcher.py e echo_server.py mostrada acima. Ele não escreve nenhum arquivo de PID; o processo filho escreve seu próprio script stop_echo.sh (kill <pid>) para o teste executar na limpeza.

Veja também

Testes em C++ — configuração do MTR, execução de suítes, registro de resultados e depuração de falhas
Criando Extensões em C++ — passos completos de compilação e configuração do CMake
Desenvolvimento em C++ — criação de VDF, tipos de argumento e tratamento de resultados

Getting Started

Server Development

Using Extensions

Creating Extensions

Por que portas fixas falham

Padrão A: Listener integrado ao servidor

Padrão B: Listener em processo externo

O lançador em primeiro plano

No teste

Mantendo a porta fora do arquivo de resultado

Gerenciamento de processos

Veja também

​Por que portas fixas falham

​Padrão A: Listener integrado ao servidor

​Padrão B: Listener em processo externo

​O lançador em primeiro plano

​No teste

​Mantendo a porta fora do arquivo de resultado

​Gerenciamento de processos

​Veja também

Por que portas fixas falham

Padrão A: Listener integrado ao servidor

Padrão B: Listener em processo externo

O lançador em primeiro plano

No teste

Mantendo a porta fora do arquivo de resultado

Gerenciamento de processos

Veja também