@argus/node

Express ve NestJS için istek metadata middleware'i. Sıfır çalışma zamanı bağımlılığı, fail-open, gövde okumaz. Node 18 ve üzeri.

Kurulum

Terminal

npm install @argus/node

Paket yalnızca Node'un kendi fetch'ini ve yerleşik modüllerini kullanır; npm install başka bir şey indirmez, postinstall betiği yoktur.

Seçenekler

argus(options)

argus({
  apiKey: string,          // zorunlu
  endpoint?: string,       // Argus backend'iniz; varsayılan "https://api.argus.dev" (henüz hizmette değil)
  sampleRate?: number,     // 0..1, varsayılan 1
  ignorePaths?: string[],  // ör. ["/health", "/metrics"]
  protection?: 'on' | 'shadow' | 'off', // varsayılan 'on'
  policyPollMs?: number,   // varsayılan 30_000, en az 1_000
})

Name
apiKey
Type
string
Description
Zorunlu. Her gönderimde x-argus-key başlığı olarak gider. Eksikse SDK açılışta bir kez uyarı yazar ve isteği olduğu gibi geçiren boş bir middleware döner; asla throw etmez.
Name
endpoint
Type
string
Description
Argus backend'inin taban adresi. Olaylar {endpoint}/v1/ingest'e, politika istekleri {endpoint}/v1/policy'ye gider. Verilmezse https://api.argus.dev kullanılır; barındırılan Argus henüz hizmette olmadığı için bugün her kurulumda kendi backend'inizin adresini açıkça verin.
Name
sampleRate
Type
number
Description
0 ile 1 arası. Yalnızca telemetriyi inceltir; koruma sayacı her isteği görür, yoksa %10 örneklemede her eşik on kat gevşerdi. 0 telemetriyi kapatır.
Name
ignorePaths
Type
string[]
Description
Tam eşleşme ya da segment öneki: /health, /health/live'ı da atlar ama /healthcheck'i atlamaz. Atlanan path'ler koruma kurallarından da muaftır.
Name
protection
Type
'on' | 'shadow' | 'off'
Description
on: panelden uygulamaya alınan kurallar bu süreçte de uygulanır. shadow: bu kurulum yalnızca işaretler, backend ne derse desin asla dokunmaz. off: politika hiç çekilmez.
Name
policyPollMs
Type
number
Description
Politikanın kaç milisaniyede bir çekileceği. Sayı değilse varsayılana döner; 1.000'in altı 1.000'e çekilir. Uygulama ve geri alma en geç bu sürede etkili olur.

Express ve NestJS

Middleware'i mümkün olduğunca erken kaydedin ki her isteği görsün.

Kayıt

import express from 'express'
import { argus } from '@argus/node'

const app = express()

app.use(
  argus({
    apiKey: process.env.ARGUS_API_KEY!,
    endpoint: 'https://argus.sirketiniz.com', // Argus backend'iniz
  }),
)

app.get('/users/:id', (req, res) => res.json({ id: req.params.id }))
app.listen(3000)

Şablonlama framework router'ına bağlanmaz, path üzerinde çalışan bir regex geçişidir; bu yüzden Express, NestJS ve çıplak http üzerinde birebir aynı davranır.

Teslimat

Olaylar bellekte biriktirilir ve POST {endpoint}/v1/ingest ucuna { "events": [...] } gövdesiyle gönderilir; hangisi önce gelirse:

50 olay birikince, ya da
her 5 saniyede bir.

Süreç kapanırken (beforeExit) son bir gönderim denenir. Tampon 10.000 olaya ulaşırsa (backend ulaşılamaz) en eskiler düşer, bellek büyümez. Başarısız gönderim atılır, tekrar denenmez: yeniden deneme fırtınası yok, uygulamaya geri basınç yok. Flush ve politika zamanlayıcıları unref edilmiştir; bir süreci telemetri için asla açık tutmazlar.

Fail-open yalnızca bir niyet değil: transport.test.mts 500, ECONNREFUSED, zaman aşımı ve bozuk fetch senaryolarında throw olmadığını, uçtan uca test ise backend SIGKILL ile öldürülmüşken isteklerin akmaya devam ettiğini ölçer.

Gereksinimler

Node 18 ve üzeri (yerleşik fetch, AbortSignal.timeout).
Express, NestJS (Express adaptörü) ya da (req, res, next) imzasını kabul eden herhangi bir middleware zinciri.
Dışarı açılan tek bağlantı: endpoint. Başka hiçbir adrese istek atılmaz.

Ne gönderilir: olay şeması