procedere-mq-sdk 0.3.1

Python SDK para LiteMQ/ProcedereMQ

ProcedereMQ

Broker de filas leve com transporte HTTP/TCP e SDKs para Go, Python e Node.js.

Segurança

• A API HTTP agora usa Basic Auth com username/password, mais proximo do modelo de brokers como ActiveMQ
• O TCP agora usa AUTH <username> <password> no lugar de token fixo
• O binario do servidor falha ao iniciar sem credenciais de API, exceto se ALLOW_INSECURE_AUTH=true for definido para desenvolvimento isolado
• O dashboard /ui usa login e senha com sessao por cookie quando UI_USERNAME e UI_PASSWORD ou UI_PASSWORD_HASH estao configurados
• Para producao, prefira UI_PASSWORD_HASH com bcrypt no lugar de senha em texto puro
• O WebSocket /ws e as rotas usadas pelo dashboard aceitam a sessao do UI; SDKs e acesso programatico usam username/password diretamente
• O servidor aplica limite de body HTTP, rate limit basico por IP e timeouts de conexao
• O container Docker roda como usuario nao-root e o docker-compose publica portas apenas em 127.0.0.1

Funcionalidades Avançadas

• Visibility Timeout: Jobs em processamento que não recebem ACK/FAIL voltam para a fila automaticamente após um tempo limite (padrão 5 min).
• DLQ Redrive: Mova todos os jobs de uma Fila de Erros (.dlq) de volta para a fila original com um clique no Dashboard ou via API.
• Delayed Jobs: Agende a execução de tarefas para o futuro usando o campo run_at.
• Dead Letter Queues (DLQ): Jobs que falham após o número máximo de tentativas são movidos automaticamente para <queue>.dlq.

Subindo com Docker

Defina as credenciais da API e do dashboard antes de iniciar:

Gere hashes bcrypt para API e UI:

make hash-password PASSWORD='senha-forte-api'
make hash-password PASSWORD='senha-forte-ui'

export API_USERNAME='api-user'
export API_PASSWORD_HASH='$2b$12$hash_bcrypt_da_api'
export UI_USERNAME='admin'
export UI_PASSWORD_HASH='$2b$12$hash_bcrypt_do_ui'
docker compose up --build

Depois acesse http://127.0.0.1:65090/ui e entre com login e senha.

SDK Go

Import:

import "github.com/jeffersontadeuleite/procedereMQ/pkg/sdk"

Como criar um Producer:

• Crie o contexto com context.Background()
• Crie o producer com sdk.NewProducer(baseURL, queue)
• Publique mensagens com producer.Publish(...)

client := sdk.NewClientWithOptions("http://127.0.0.1:65090", sdk.ClientOptions{
    Username: "api-user",
    Password: "senha-forte-api",
})
ctx := context.Background()
producer, err := sdk.NewProducerWithClient(client, "emails")
if err != nil {
    return err
}

job, err := producer.Publish(ctx, map[string]any{
    "to": "[e-mail]",
    "template": "welcome",
}, sdk.PublishOptions{MaxRetry: 3})
if err != nil {
    return err
}
fmt.Println("job criado:", job.ID)

Como criar um Consumer:

• Crie o consumer com sdk.NewConsumer(baseURL, queue)
• Receba jobs com consumer.Receive(ctx)
• Finalize com consumer.AckJob(ctx, job) ou consumer.FailJob(ctx, job)

client := sdk.NewClientWithOptions("http://127.0.0.1:65090", sdk.ClientOptions{
    Username: "api-user",
    Password: "senha-forte-api",
})
ctx := context.Background()
consumer, err := sdk.NewConsumerWithClient(client, "emails")
if err != nil {
    return err
}

job, err := consumer.Receive(ctx)
if err != nil {
    if errors.Is(err, sdk.ErrQueueEmpty) {
        return nil
    }
    return err
}

if err := consumer.AckJob(ctx, job); err != nil {
    return err
}

SDK Python

Instalação:

pip install procedere-mq-sdk==0.3.1

Como criar um Producer:

• Crie o cliente com LiteMQClient(base_url)
• Crie o producer com client.producer("nome-da-fila")
• Publique mensagens com producer.publish(...)

from python_sdk import LiteMQClient

client = LiteMQClient("http://127.0.0.1:65090", username="api-user", password="senha-forte-api")
producer = client.producer("emails")

job = producer.publish(
    {"to": "[e-mail]", "template": "welcome"},
    max_retry=3,
)
print("job criado:", job["id"])

Como criar um Consumer:

• Crie o client com LiteMQClient(base_url)
• Crie o consumer com client.consumer("nome-da-fila")
• Receba jobs com consumer.receive()
• Finalize com consumer.ack(job) ou consumer.fail(job)

from python_sdk import LiteMQClient, QueueEmptyError

client = LiteMQClient("http://127.0.0.1:65090", username="api-user", password="senha-forte-api")
consumer = client.consumer("emails")

try:
    job = consumer.receive()
    consumer.ack(job)
except QueueEmptyError:
    pass

SDK Node.js

Instalacao:

npm install procedere-mq-sdk

Como criar um Producer:

• Crie o cliente com new LiteMQClient(baseUrl)
• Crie o producer com client.producer("nome-da-fila")
• Publique mensagens com producer.publish(...)

const { LiteMQClient } = require("procedere-mq-sdk");

const client = new LiteMQClient("http://127.0.0.1:65090", {
  username: "api-user",
  password: "senha-forte-api",
});
const producer = client.producer("emails");

const job = await producer.publish(
  { to: "[e-mail]", template: "welcome" },
  { maxRetry: 3 }
);

console.log("job criado:", job.id);

Como criar um Consumer:

• Crie o client com new LiteMQClient(baseUrl)
• Crie o consumer com client.consumer("nome-da-fila")
• Receba jobs com consumer.receive()
• Finalize com consumer.ack(job) ou consumer.fail(job)

const { LiteMQClient, QueueEmptyError } = require("procedere-mq-sdk");

const client = new LiteMQClient("http://127.0.0.1:65090", {
  username: "api-user",
  password: "senha-forte-api",
});
const consumer = client.consumer("emails");

try {
  const job = await consumer.receive();
  await consumer.ack(job);
} catch (error) {
  if (error instanceof QueueEmptyError) {
    // fila vazia
  } else {
    throw error;
  }
}

Publicação

Go SDK

make publish-go-sdk VERSION=0.3.1

Python SDK (PyPI)

make check-python-sdk
make publish-python-sdk TWINE_REPOSITORY=pypi

Node.js SDK (npm)

make check-node-sdk
make publish-node-sdk

Release De Producao

O projeto agora tem um script unico para publicar:

• imagem Docker em jebob28/procederemq
• SDK Go por tag git
• SDK Python no PyPI
• SDK Node.js no npm

Antes de rodar, deixe o worktree limpo e exporte os tokens no ambiente:

export NPM_TOKEN='seu-token-npm'
export PYPI_TOKEN='seu-token-pypi'

Depois execute:

make release-prod VERSION=0.3.1

O script:

• sincroniza versao em pyproject.toml, node_sdk/package.json, README.md e testes automatizados
• roda testes Go, Python e Node
• cria commit release: vX.Y.Z
• cria e envia a tag git vX.Y.Z
• publica PyPI, npm e Docker