flowingts / FlowingApp

Classe: FlowingApp

Definido em: src/core/app.ts:68

O app. É uma fachada (Facade) sobre o registro de rotas, as rotas do próprio framework (health, OpenAPI), o servidor e o pipeline da requisição: a API pública fica aqui, e o trabalho fica nesses componentes.

Construtores

Construtor

new FlowingApp(opts?): FlowingApp

Definido em: src/core/app.ts:76

Parâmetros

opts?

AppOptions = {}

Retorna

FlowingApp

Propriedades

log

readonly log: Logger

Definido em: src/core/app.ts:69

Métodos

callback()

callback(): (req, res) => void

Definido em: src/core/app.ts:327

Listener (req, res) do app, para usar com qualquer servidor do Node: https.createServer(opts, app.callback()), http2 em modo compat, testes etc. (F-09).

Retorna

(req, res) => void

---

close()

close(graceMs?): Promise<void>

Definido em: src/core/app.ts:350

Para de aceitar conexões, encerra as ociosas e espera as requisições em andamento terminarem. Depois de graceMs, força o fechamento das restantes.

Parâmetros

graceMs?

number = 10_000

Retorna

Promise<void>

---

group()

group(options, define): this

Definido em: src/core/app.ts:184

Agrupa mount()s sob um prefixo, middlewares e guards comuns. Não é um container: é só composição, com a mesma semântica do mount(). Grupos podem ser aninhados.

app.group({ prefix: '/v2', middlewares: [authenticate], guards: [isAdmin] }, (g) =>
  g.mount(UserRoutes).mount(new OrderRoutes(db)),
);

Ordem de execução: middlewares dos grupos (de fora para dentro) → do mount() → da classe → do método.

Parâmetros

options

GroupOptions

define

(group) => unknown

Retorna

this

---

handle()

handle(ctx): Promise<void>

Definido em: src/core/app.ts:319

Executa o pipeline completo para um contexto já criado.

Parâmetros

ctx

Context

Retorna

Promise<void>

---

health()

health(opts?): this

Definido em: src/core/app.ts:300

Healthchecks para load balancers e orquestradores (Kubernetes, ECS…).

• GET /livez: o processo está de pé (200 sempre).
• GET /readyz: pronto para receber tráfego. Roda os checks (banco, fila…) e responde 503 se algum falhar ou estourar o tempo, e também durante o encerramento.

As rotas são servidas antes dos middlewares globais (sondas não têm credenciais nem devem consumir rate limit); use guards/middlewares aqui para restringir.

Parâmetros

opts?

HealthOptions = {}

Retorna

this

---

inject()

inject(opts): Promise<InjectResponse>

Definido em: src/core/app.ts:355

Executa uma requisição em memória, sem rede. Ideal para testes (F-09).

Parâmetros

opts

string | InjectOptions

Retorna

Promise<InjectResponse>

---

listen()

Assinatura

listen(options): Promise<Server<typeof IncomingMessage, typeof ServerResponse>>

Definido em: src/core/app.ts:332

Sobe o servidor HTTP (ou HTTPS, com tls) e resolve quando ele está aceitando conexões (F-09, F-33).

Parâmetros

options

ListenOptions & object

Retorna

Promise<Server<typeof IncomingMessage, typeof ServerResponse>>

Assinatura

listen(options?): Promise<Server<typeof IncomingMessage, typeof ServerResponse>>

Definido em: src/core/app.ts:333

Sobe o servidor HTTP (ou HTTPS, com tls) e resolve quando ele está aceitando conexões (F-09, F-33).

Parâmetros

options?

number | ListenOptions

Retorna

Promise<Server<typeof IncomingMessage, typeof ServerResponse>>

---

mount()

Assinatura

mount<T>(ref, options?): MountedGroup<T>

Definido em: src/core/app.ts:167

Registra uma classe com @Router (F-28). Aceita a classe (construtor sem argumentos) ou uma instância pronta (B-10), e opções aplicadas no ponto de composição:

app
  .mount(HealthRoutes)
  .mount(new UserRoutes(repo), { prefix: '/v2/users', middlewares: [auth], except: (r) => [r.remove] })
  .get('/legacy/:id', (r) => r.getUser);      // mapeamento manual (F-30)

Parâmetros de tipo

T

T extends object

Parâmetros

ref

new () => T

options?

MountOptions<T>

Retorna

MountedGroup<T>

Assinatura

mount<T>(ref, options?): MountedGroup<T>

Definido em: src/core/app.ts:168

Registra uma classe com @Router (F-28). Aceita a classe (construtor sem argumentos) ou uma instância pronta (B-10), e opções aplicadas no ponto de composição:

app
  .mount(HealthRoutes)
  .mount(new UserRoutes(repo), { prefix: '/v2/users', middlewares: [auth], except: (r) => [r.remove] })
  .get('/legacy/:id', (r) => r.getUser);      // mapeamento manual (F-30)

Parâmetros de tipo

T

T extends object

Parâmetros

ref

T extends new (...args) => unknown ? never : T

options?

MountOptions<T>

Retorna

MountedGroup<T>

---

onClose()

onClose(hook): this

Definido em: src/core/app.ts:151

Roda no close(), depois que o servidor fecha, qualquer que seja a origem (sinal, teste, código), e antes do shutdown.onShutdown. Erros são logados e fazem o close() rejeitar ao final (F-04).

Parâmetros

hook

OnCloseHook

Retorna

this

---

onError()

onError(h): this

Definido em: src/core/app.ts:112

Parâmetros

h

OnErrorHook

Retorna

this

---

onRequest()

onRequest(hook): this

Definido em: src/core/app.ts:132

Roda no início de cada requisição, antes da validação do Host e dos middlewares: abrir um span, contar requisições ativas. Toda requisição que passa por aqui também passa pelo onResponse. É síncrono; erros são só logados (F-38).

Parâmetros

hook

OnRequestHook

Retorna

this

---

onResponse()

onResponse(hook): this

Definido em: src/core/app.ts:142

Roda exatamente uma vez quando a requisição termina, com status, duração, outcome (completed, aborted, error), motivo do cancelamento, tempo até os headers, rota e se foi stream: métricas, tracing, auditoria. Pode ser assíncrono; erros são só logados (F-04, F-38).

Parâmetros

hook

OnResponseHook

Retorna

this

---

onSend()

onSend(hook): this

Definido em: src/core/app.ts:122

Roda imediatamente antes de escrever uma resposta com corpo (exceto streams), inclusive em erros e 404. É síncrono: pode alterar headers (ETag, assinatura) ou devolver { body, contentType } novos. Se lançar, o erro é logado e a resposta original é enviada (F-04).

Parâmetros

hook

OnSendHook

Retorna

this

---

openapi()

openapi(opts?): this

Definido em: src/core/app.ts:279

Serve o documento OpenAPI 3.1 gerado das rotas (/openapi.json) e, com docs, o Swagger UI (F-16). As duas rotas passam pelos middlewares globais e pelos middlewares/guards informados aqui: app.openapi({ guards: [isAdmin] }). O documento é gerado na primeira requisição, depois dos mount().

Parâmetros

opts?

OpenAPIOptions = {}

Retorna

this

---

openapiDocument()

openapiDocument(opts?): Record<string, unknown>

Definido em: src/core/app.ts:312

Documento OpenAPI 3.1 das rotas registradas até agora, para gravar em arquivo ou testar (F-16). Com virtual hosts, é por host (F-35): { host: 'api.exemplo.com' } traz as rotas desse host e as sem host; sem host, só as sem host. Domínios diferentes nunca se misturam num mesmo documento.

Parâmetros

opts?

OpenAPIOptions = ...

Retorna

Record<string, unknown>

---

reloadTLS()

reloadTLS(tls): void

Definido em: src/core/app.ts:342

Troca os certificados sem reiniciar nem derrubar conexões (renovação, ACME externo). Conexões novas usam os novos; as abertas seguem com os antigos. Um certificado inválido lança erro e mantém os atuais.

Parâmetros

tls

TlsOptions

Retorna

void

---

static()

static(prefix, root, opts?): this

Definido em: src/core/app.ts:229

Serve os arquivos de root em GET prefix/* (F-13). É uma rota como as outras: vale group() (host, guards, middlewares), 404/405 e a checagem de conflitos. Não entra no OpenAPI.

app.static('/assets', './public', { maxAge: '7d', immutable: true });
app.static('/', './dist', { fallback: 'index.html' }); // SPA

Caminhos que saem da raiz (.., symlinks), arquivos ocultos e diretórios sem índice respondem 404.

Parâmetros

prefix

string

root

string

opts?

StaticOptions = {}

Retorna

this

---

use()

use(mw): this

Definido em: src/core/app.ts:107

Parâmetros

mw

Middleware

Retorna

this