Saluran Dasar (YPP)
Saluran Dasar Yabanin (YPP) ialah penghantar pemeriksaan dan mutasi boleh atur
cara yang berjalan atas trafik gerbang: dasar YAML deklaratif, pengimbas HTTP
luaran, hakim LLM, mutator kandungan dan pencabangan bersyarat — digubah dan
dilaksanakan di satu tempat, middleware gerbang. Ia mati secara lalai: jika
YABANIN_POLICY_MODE tidak ditetapkan, masa jalan saluran tidak sekali-kali
dibina dan pengendalian permintaan serupa bit demi bit dengan pelaksanaan tanpa
ciri tersebut.
Dasar ialah objek keselamatan berskop organisasi. Penguatkuasaan membaca policystore sahaja — tiada konfigurasi dasar per permintaan (dibekalkan SDK), jadi klien tidak sekali-kali boleh memintas dasar pentadbir.
1. Seni bina
pkg/pipeline pure core: payload/finding/result types, the Step
contract, YAML compilation, the execution engine.
No DB/HTTP/LLM/logging side effects.
pkg/pipeline/builtins 20 deterministic steps (15 detectors + 5 mutators).
pkg/pipeline/callout external HTTP detector/mutator steps (SSRF-guarded).
pkg/pipeline/llmjudge LLM-judge step through the gateway's own upstream pool.
pkg/pipeline/script `when` condition engines: expr (default), lua, starlark.
pkg/pipeline/streaming SSE primitives: prefix gate, chunk carry, final check.
pkg/policystore versioned policy storage + attachments (migration 0008).
gateway middleware the single integration point: compiles org policies per
version, runs attached pipelines on each hook (OP-8).
Gerbang membina satu enjin bagi setiap proses dengan registri langkah penuh:
terbina dalam, callout (hanya apabila senarai benarkan egress dikonfigurasi),
llm_judge, pengawal alat builtin/toolpolicy, langkah verdik decide dan
pemegang tempat no-op route_hint, serta ketiga-tiga enjin syarat (expr,
lua, starlark).
2. Konsep
Cangkuk dan jenis muatan
Sesuatu dasar mengisytiharkan permukaan gerbang (hooks) yang ia jalankan.
Cangkuk menentukan jenis muatan yang diserahkan kepada langkah:
| Cangkuk | Jenis muatan | Tercetus |
|---|---|---|
pre_upstream | request | sebelum panggilan huluan |
post_upstream | response | selepas respons huluan |
stream_prefix | stream_prefix | awalan strim tertimbal (lihat §7) |
stream_final | stream_final | agregat strim penuh |
tool_pre | tool_args | sebelum panggilan alat/MCP |
tool_post | tool_result | selepas panggilan alat/MCP |
Muatan membawa senarai mesej, badan mentah (dan bagi stream_* teks ketulan),
serta metadata permintaan baca sahaja (org, key, model, provider,
label, tag) dan, pada muatan permintaan, pengepala permintaan huluan.
Tindakan dan gubahan
Setiap dapatan membawa satu tindakan pada skala ketegasan tetap tolak > topeng > bendera > benarkan:
deny— sekat permintaan / panggilan alat / strim (memintas litar larian).mask— teruskan, tetapi hanya dengan muatan yang dimutasi.flag— teruskan tanpa perubahan, rekod pemerhatian.allow— tiada apa-apa untuk diambil tindakan.
Apabila beberapa dasar yang dilampirkan sepadan dengan sesuatu permintaan,
semuanya berjalan (disusun mengikut keutamaan lampiran, organisasi → kunci →
model): dapatan disatukan, verdik ialah yang paling ketat yang diperhatikan, dan
deny pertama memintas litar kerja yang selebihnya (langkah yang dilangkau
masih muncul dalam jejak). Tindakan yang tidak diketahui daripada langkah yang
bermasalah ditarafkan sebagai tolak — gagal tertutup. Pengesan sentiasa
memerhatikan teks termutasi yang terkini, termasuk merentas sempadan dasar.
Setiap langkah terkompil bagi setiap larian dijejak tepat sekali (ran,
skipped, error, timeout, dengan tempoh dan ralat) — log keputusan
bergantung pada kelengkapan ini.
Mod dan suis pemati
mode: enforce— dapatan menaikkan verdik; mutator menulis semula muatan.mode: shadow— dasar tidak sekali-kali memutasi dan tidak sekali-kali menaikkan verdik; dapatan direkodkan untuk pembezaan "apa yang akan berlaku". Ini ialah laluan pelancaran yang disyorkan (bayang → semak log keputusan → kuatkuasa).
Suis pemati seluruh proses YABANIN_POLICY_MODE (lalai off):
| Nilai | Tingkah laku |
|---|---|
off | masa jalan tidak sekali-kali dibina; setiap cangkuk ialah no-op (lalai) |
shadow | setiap dasar diturunkan kepada bayang semasa masa kompil |
enforce | dasar berjalan dalam mod tersimpannya |
Nilai yang tidak diketahui dileraikan kepada off dengan amaran. Panggilan
hakim yang dibuat oleh gerbang sendiri membawa penanda dalaman (§6.2); trafik
masuk yang mengemukakan pengepala hakim ditolak, bukan dikecualikan (§6.2).
3. YAML dasar (apiVersion ypp/v1)
Satu dasar bagi setiap dokumen; nama file mesti sama dengan name dasar
apabila diurus sebagai kod (§8). Contoh kerja sebenar ada dalam
deploy/policies/_example/pii-guard.yaml dan pek deploy/policies/_pack/.
apiVersion: ypp/v1
kind: Policy
name: pii-guard # required identity (metrics, decision log)
mode: shadow # shadow | enforce
hooks: [pre_upstream] # at least one, no duplicates
steps:
- id: scan # parallel group head: the detectors below
parallel: [pii, secrets] # run concurrently, join before the next step
- id: pii
detector: builtin/national-pii
- id: secrets
detector: builtin/secrets
- id: verdict
decide: |
deny if findings.any(f -> f.category matches 'secrets.*' and f.severity == 'high')
mask if findings.any(f -> f.action == 'mask')
flag otherwise
Pengesahan adalah ketat: medan YAML yang tidak diketahui ialah ralat pemuatan;
apiVersion mesti ypp/v1, kind mesti Policy, name dan mode wajib, id
langkah adalah unik, dan setiap langkah membawa tepat satu medan jenis
(detector | mutator | callout | llm_judge | decide | route_hint).
Pilihan bagi setiap langkah:
| Medan | Maksud |
|---|---|
when | sumber syarat pilihan (§4); dikompil sekali semasa pemuatan dasar |
when_engine | semat enjin syarat (expr/lua/starlark); wajib sebaik sahaja lebih daripada satu enjin didaftarkan |
timeout | bajet bagi setiap langkah, sintaks tempoh Go (50ms, 2s); tamat masa mengikut on_error |
on_error | fail_closed (lalai; kegagalan menolak dan memintas litar) | fail_open | fail_open+flag (menambah dapatan bendera step_error sintetik) |
parallel | id langkah dasar ini yang berjalan serentak dengan langkah ini sebagai satu kumpulan gabung; setiap peserta mesti pengesan (kumpulan adalah baca sahaja; mutator dalam kumpulan ialah ralat kompil), tiada bersarang |
params | parameter kilang langkah (§5); kunci yang dikhaskan bagi jenis (url, model, prompt_ref, expr, target) bertembung sebagai ralat kompil |
Lampiran (pihak yang dasar terpakai kepadanya) disimpan bersama dasar, bukan dalam YAML — lihat §8 untuk blok penyelarasan yang diisytiharkan git dan API pentadbir (§9).
4. Syarat (when)
Sumber when dinilai pada masa larian terhadap konteks baca sahaja larian
setakat ini: dapatan yang direkod, jejak langkah (tempoh/hasil), dan meta
permintaan. Kompilasi berlaku sekali bagi setiap langkah semasa pemuatan dasar;
syarat tanpa enjin berdaftar ialah ralat pemuatan, tidak sekali-kali langkau
senyap. Ralat syarat mengikut mod on_error langkah (gagal tertutup secara
lalai).
Tiga enjin dihantar dan didaftarkan oleh gerbang: expr (minimum, bebas gelung
— lalai yang dimaksudkan), lua (gopher-lua dalam kotak pasir dengan bajet
arahan) dan starlark. Enjin boleh ditukar di sebalik satu antara muka;
menukar bahasa tidak mengubah model dasar YAML.
Jenis langkah decide ialah DSL verdik yang berasingan dan bebas enjin
(berasaskan baris, peraturan sepadan pertama menang):
deny if findings.any(f -> f.category matches 'secrets.*' and f.severity == 'high')
mask if findings.any(f -> f.action == 'mask')
flag otherwise
Medan: category, severity, action, step, span; operator == dan
matches (* awalan bintang hujung); baris otherwise menetapkan sandaran
(lalai allow). Langkah decide hanya menaikkan verdik — ia tidak sekali-kali
memutasi atau menambah dapatan.
5. Langkah terbina dalam
Nama registri dibekukan — dasar merujuknya mengikut rentetan. Parameter pilihan yang biasa pada setiap langkah:
kinds— hadkan jenis muatan yang diperiksa (lalai: keenam-enam jenis; langkah skema JSON lalai kepada jenis keluaran, langkah permintaan sahaja menyematrequest).action— tindakan yang dibawa dapatan langkah:flag(lalai),maskataudeny(allowbukan tindakan pengesan). Kegagalan pengesahan kilang ialah ralat pemuatan dasar.
Pengesan
| Langkah | Kategori | Parameter (selain yang biasa) |
|---|---|---|
builtin/national-pii | innsnils, pan, ru_passport, ogrn + nombor identiti BR/IN/MY/AE/ZA/NG/KE/EG | — (set RU tetap + 9 bidang kuasa; disahkan checksum/Luhn) |
builtin/secrets | secret (+ nilai JSON berkunci kelayakan) | — (bentuk kunci penyedia, pengepala PEM, bentuk JWT; bukti tidak sekali-kali dipetik — [REDACTED_SECRET]) |
builtin/injection | injection | — (frasa suntikan gesaan RU + EN) |
builtin/word-count | word_count | min, max (sekurang-kurangnya satu batas wajib; max 0 = tanpa batas) |
builtin/char-count | char_count | min, max (rune, bukan bait) |
builtin/sentence-count | sentence_count | min, max (heuristik penamat luar talian) |
builtin/contains | contains | words (senarai wajib), mode any|all|none (lalai any), case_insensitive (lalai true) |
builtin/regex | regex | pattern (wajib, RE2; pengkuantiti bersarang dan bom pengembangan ialah ralat pemuatan), invert, case_insensitive, max_input (lalai 1 MiB, siling 64 MiB — saiz lampau menggagalkan langkah) |
builtin/json-schema | json_schema | schema (Skema JSON sebaris wajib; dikompil semasa pemuatan) |
builtin/json-keys | json_keys | keys (laluan bertitik wajib), mode any|all|none (lalai all) |
builtin/url-check | url | schemes (lalai ["https","http"]), allow_hosts, deny_hosts (kad liar *.suffix); sepenuhnya luar talian — tidak sekali-kali mengambil |
builtin/code-detect | code.<lang> | languages (subset sql|python|typescript, lalai semua) |
builtin/language | language | allowed (subset tidak kosong yang wajib daripada ru|en|other; heuristik dominasi skrip) |
builtin/model-whitelist | model | models (corak glob wajib; model tidak diketahui/kosong = pelanggaran) |
builtin/metadata-required | metadata | keys (medan/label meta) dan/atau labels (pasangan label=nilai); sekurang-kurangnya satu wajib |
Mutator
| Langkah | Kesan | Parameter |
|---|---|---|
builtin/redact | menggantikan rentang sensitif dapatan larian (dan/atau coraknya sendiri) dengan token [REDACTED:<category>:n] | categories (nama tepat atau .* hujung), patterns (senarai {category, pattern}), max_input |
builtin/pseudonymize | pseudonimisasi boleh balik: rentang menjadi alias {{YPP_n}} yang stabil; penggantian mengalir keluar sahaja — tiada penggantian songsang ke dalam respons | categories, patterns, carry none (lalai)|session, max_input |
builtin/header-rewrite | menyunting pengepala permintaan huluan (pembuangan dikenakan sebelum set; suntikan CRLF/NUL ialah ralat pemuatan) | set (peta), remove (senarai); permintaan sahaja |
builtin/model-rewrite | menulis semula model permintaan (jahitan sempadan data: halakan permintaan yang membawa PII kepada model dalam rantau); setiap tulis semula direkodkan sebagai dapatan bendera model_rewrite | to (wajib), from (prasyarat pilihan); permintaan sahaja |
builtin/partials-substitute | menggantikan token {{partials.NAME}} (satu laluan, tidak sekali-kali diimbas semula) | on_missing skip (lalai)|error; stor sumber disambungkan di sisi pelayan (studio prompt, §6.1) |
builtin/pseudonymize dengan carry: session mengekalkan peta alias melalui
pembawa sesi supaya asal yang sama dipetakan kepada alias yang sama merentas
giliran; pembawa dilucutkan sebelum penghantaran ke huluan atau kepada klien.
Dua lagi jenis langkah didaftarkan oleh gerbang: builtin/toolpolicy (pagar
panggilan alat dalam Dasar alat sebagai langkah saluran)
dan langkah jahitan decide / route_hint (§4). route_hint kini ialah
pemegang tempat no-op — semantik penghalaan ialah keputusan kemudian.
6. Langkah luaran
6.1 Panggilan keluar (pengesan/mutator HTTP)
Langkah callout: membuat POST unjuran muatan ke pengimbas luaran dan
memetakan respons kepada dapatan (mod detect) atau mengenakan semula
kandungan yang dimutasi (mod mutate).
- id: presidio
callout: http://presidio.internal:3000/analyze
params:
mode: detect # detect | mutate
expose: messages # messages (default) | body | fields:a,b,c
response: findings # findings (default) | boolean (JSON true/false)
finding_category: presidio # default category for boolean mode
max_response_bytes: 65536
timeout: 250ms
on_error: fail_open+flag
Unjuran (expose) menghadkan apa yang meninggalkan gerbang: messages
menghantar kandungan mesej (dicantum dengan \n untuk detect, satu elemen
tatasusunan bagi setiap mesej untuk mutate), body menghantar badan mentah
(risiko yang didokumenkan — dayakan hanya bagi pengimbas yang terikat secara
kontrak kepada domain data yang sama), fields:a,b menghantar hanya medan aras
atas tersebut bagi badan objek JSON. Metadata org/key/model tidak sekali-kali
keluar.
Kontrak respons. detect/findings menjangkakan
{"findings":[{"category","severity","action","span","evidence"}]} —
category wajib, tindakan yang tidak diketahui ditarafkan sebagai tolak.
detect/boolean menjangkakan JSON true/false. mutate mesti menjawab
{"content": ...} yang sepadan dengan unjuran secara tepat: bilangan mesej
yang sama, rentetan badan, atau objek yang set kuncinya sama dengan set medan
yang diunjurkan. Verdik pengimbas (2xx yang sah) tidak sekali-kali menjadi
ralat; kegagalan rangkaian, bukan 2xx, pelanggaran kontrak dan penolakan
pemutus ialah ralat langkah yang mengikut on_error.
Keselamatan egress (tidak boleh dirunding). Langkah hanya dibina apabila
pengendali mengkonfigurasi YABANIN_POLICY_CALLOUT_ALLOW_HOSTS (domain tepat
yang dipisahkan koma, atau *.suffix); setiap URL disahkan terhadap senarai
itu pada masa kompil dasar. Pada masa dail, pengawal SSRF menyemat jawapan DNS
dan menolak semua alamat terpelihara (gelung balik, RFC1918, pautan
tempatan/metadata awan), lalu menutup tetingkap pengikatan semula DNS. Tiada
lencongan, tiada cubaan semula, pemutus litar bagi setiap URL, penyahduplikasi
singleflight bagi panggilan serupa yang serentak, dan tamat masa bagi setiap
langkah. Tanpa senarai benarkan, dasar callout gagal semasa pemuatan — egress
tidak sekali-kali boleh lebih luas daripada senarai pengendali.
6.2 Hakim LLM
Langkah llm_judge menghantar satu giliran perbualan kepada model hakim
melalui jentera huluan gerbang sendiri (kolam berpengawal SSRF yang sama yang
digunakan oleh trafik klien — pengelas berdaulat dan di premis sendiri ialah
sasaran kelas pertama) dan memetakan verdik kepada dapatan:
- id: judge_tox
llm_judge:
model: "$(sovereign-classifier)" # required; literal or $(registry indirection)
prompt_ref: "judges/toxicity@2" # required; versioned prompt resource
params:
mode: input # input (last user turn, default) | output (last assistant turn)
threshold: 0.8 # confidence >= threshold → deny; below → flag (default 0.8)
categories: [toxicity]
timeout: 2s
on_error: fail_open+flag
Rujukan prompt dileraikan melalui PromptSource berversi — file terbenam
(judges/<name>/<version>.md, contohnya judges/toxicity@1, @2) ialah
lalai, dan studio prompt membekalkan sumber peringkat organisasi. Suhu disemat
pada 0 supaya verdik adalah deterministik. Dapatan hakim diletakkan dalam
ruang nama judge.<category> dan tidak sekali-kali bertembung dengan kategori
pengesan. Verdik yang cacat ialah ralat langkah (on_error terpakai);
keyakinan yang ditinggalkan dikira sebagai 1.0 (gagal tertutup).
Pengecualian rekursi (kontrak keras). Setiap panggilan hakim yang dibuat
oleh gerbang sendiri membawa judge=true dalam meta muatan dan pengepala
X-Yabanin-Judge: true pada wayar; penanda muatan dalaman mengecualikan
panggilan sintetik itu daripada saluran, jadi model hakim yang dilayan oleh
gerbang yang sama tidak sekali-kali memasuki semula. Pengepala wayar sahaja
tidak memberikan apa-apa: mana-mana permintaan masuk yang mengemukakan
X-Yabanin-Judge — nilai true, false, arbitrari, kosong, atau berulang —
tidak dipercayai dan ditolak dengan 400 judge_reentry_unsupported pada
sempadan pra-huluan yang dikongsi, selepas pengesahan dan penyelesaian laluan,
sebelum sebarang panggilan huluan. Kegagalan stor dasar yang sejuk dalam mod
kuatkuasa mengekalkan keutamaan 503 sedia ada berbanding penolakan ini.
Penyesuai keluar enggan menghantar panggilan hakim yang tidak bertanda.
7. Semantik penstriman
Dasar penstriman menggunakan pintu awalan, bawaan ketulan, dan semakan akhir dalam laluan SSE:
- Lalai strim. Apabila masa jalan dasar aktif dalam mod penguatkuasaan
dan sesuatu dasar dilampirkan pada
stream_prefix,builtin/redactataubuiltin/pseudonymizetanpakindsmenyertakanstream_prefixsecara lalai. Lalai tanpakindsyang sama menyertakanstream_finalapabila cangkuk itu dilampirkan; senaraikindsyang eksplisit menyempitkan skop langkah. Ini ialah lalai biasa yang sama seperti yang diterangkan dalam §5.stream_finalmemeriksa strim yang telah selesai selepas pengeluaran dan tidak boleh menghalang atau menarik balik bait yang sudah dihantar. - Pintu awalan dan bawaan ketulan. Apabila dasar
stream_prefixdilampirkan, gerbang menilai satu petikan awalan yang ditangkap. Lalai ialah 64 token anggaran atau 500 ms daripada delta tidak kosong yang pertama, mana-mana yang tercetus dahulu;prefix_tokensatauprefix_delay_msboleh menindihnya. Strim tertimbal yang lebih pendek disiram pada hujung strim. Nilai lengkap yang ditemui dalam petikan itu boleh diubah sebelum dilepaskan. Bawaan ketulan mengenakan penggantian yang dipelajari bagi nilai itu kepada kejadian kemudian, termasuk kejadian yang terpecah merentas ketulan. Ia tidak menemui nilai baharu yang tiada dalam petikan, atau yang pertama kali dilihat selepas laluan terus bermula, jadi nilai sedemikian tidak dijamin ditemui atau disembunyikan. Bingkai kandungan SSE yang dimutasi dikod semula sambil pembingkaian peristiwa dikekalkan;[DONE]dan bingkai tanpa delta kandungan lalu tanpa perubahan. Apabila cache strim didayakan, transform berjalan sebelum penulis rakaman cache, jadi klien dan cache memerhatikan bait yang diubah yang sama. - Tolak awalan.
denydaripada petikan awalan membatalkan aliran sebelum sebarang bait yang ditahan dilepaskan; gerbang menghantar bingkai ralat kanonik dandata: [DONE]. - Jika output tidak berubah. Semak bahawa masa jalan dasar didayakan
dalam mod penguatkuasaan, dasar dilampirkan pada organisasi, model, endpoint
dan cangkuk
stream_prefixyang dimaksudkan, dan senaraikindsyang eksplisit tidak mengecualikanstream_prefix. Semak bahawa sasaran sintetik yang lengkap tiba dalam awalan yang ditangkap sebelum ia disiram. Betulkan lampiran ataukinds, atau laraskan parameter awalan, kemudian sahkan dengan strim sintetik tempatan. Tetingkap awalan yang lebih besar boleh melengahkan bait pertama dan tetap tidak boleh menjamin penemuan nilai yang pertama kali muncul selepas laluan terus bermula. - Semakan akhir. Bingkai yang telah dihantar terkumpul menjadi dokumen
chat.completionsintetik, yang diperiksa oleh dasarstream_finalselepas pengeluaran.denyakhir tidak boleh menarik balik bait; ia merosot kepada hasil yang dibenderakan dan direkodkan dalam log keputusan serta metrik.
8. Konfigurasi sebagai kod (git → policystore)
Git ialah sumber kebenaran tunggal bagi pengisytiharan dasar. Lihat
deploy/policies/README.md untuk aliran kerja penuh; versi ringkas:
- Pengisytiharan berada di
deploy/policies/<org-slug>/<policy-name>.yaml— dokumen 1 ialah dasar (disimpan sebagaimana adanya), dokumen 2 pilihan selepas---ialah blok penyelarasan (enabled,attachments). yb policies reconcilemerancang perbezaan (dry-run secara lalai);--applymenumpu pangkalan data kepada git;--prune(bahaya) juga memadam dasar DB yang tidak diliputi oleh pengisytiharan. CI menjalankan dry-run supaya pengisytiharan yang rosak menggagalkan binaan.- Hanyutan dilaporkan, tidak sekali-kali digabungkan secara senyap:
suntingan DB yang dibuat di luar git ialah
DRIFTdalam pelan dan ditimpa oleh versi baharu semasa digunakan (versi tidak boleh diubah, jadi tiada apa-apa yang dimusnahkan). API pentadbirGET /api/organizations/{id}/policies/driftmelaporkan status bagi setiap dasarmanaged/drift/unmanagedtanpa checkout repositori. - Pek
deploy/policies/_pack/sovereign-default.yaml(PII nasional + rahsia + suntikan, mod bayang, lampiran seluruh organisasi) dihantar MATI — ia diselaraskan hanya dengan--include-pack, dan walaupun begitu mendarat dalam keadaan dinyahdayakan.
Setiap perubahan yang digunakan merekod SHA git semasa sebagai git_sha
versi, supaya log keputusan dan metrik terikat kembali kepada semakan
pengisytiharan yang tepat.
Pembatalan cache oleh penyelarasan bergantung pada CLI dan gerbang yang
menggunakan stor dasar Postgres yang sama dan stor versi dasar Redis. Dengan
--apply, selepas penggunaan bagi setiap organisasi yang berjaya dan yang
mengubah dasar, CLI cuba mengemas kini kunci versi dasar Redis organisasi itu.
Setiap gerbang mengkuar kunci pada permintaan dan mengambil versi boleh baca
yang berubah pada permintaan seterusnya; tiada tolakan latar belakang. Dry-run,
penggunaan yang tidak berubah, dan penggunaan bagi setiap organisasi yang gagal
tidak mengeluarkan kenaikan versi. Kegagalan kenaikan Redis dilaporkan sebagai
amaran dan tidak menggulung balik penulisan pangkalan data. Penggunaan bagi
setiap organisasi terdiri daripada berbilang operasi stor, jadi operasi yang
kemudian boleh gagal selepas penulisan yang terdahulu telah dikomit; arahan
itu melaporkan kegagalan organisasi dan tidak menaikkan kuncinya. Betulkan
punca dan jalankan semula penyelarasan supaya bertumpu.
Mana-mana versi boleh baca yang berbeza daripada versi cache yang diketahui
mencetuskan percubaan penyegaran stor pada permintaan seterusnya. Kunci Redis
yang tiada dibaca sebagai versi 0, jadi ia mencetuskan percubaan itu apabila
versi cache diketahui dan bukan sifar. Sempadan umur cache keras 30 saat
terpakai apabila kuar versi tidak tersedia, nilai boleh bacanya sama dengan
versi cache (termasuk kunci yang tiada yang dibaca sebagai 0 apabila versi
cache juga 0), atau pemuatan stor yang berjaya tidak menangkap versi. Kuar
ini tidak memperbaharui umur cache, yang diukur daripada pemuatan stor dasar
yang berjaya terakhir. Pada atau selepas sempadan, permintaan seterusnya cuba
penyegaran stor. Pemuatan stor yang gagal mengekalkan petikan terakhir yang
diketahui baik dan umur asalnya; permintaan yang kemudian mencuba semula, dan
pemuatan yang berjaya mengambil dasar yang disimpan. Penyegaran dipacu
permintaan, dan ketersediaan stor dasar masih penting.
9. Policystore dan API pentadbir
Policystore (migrasi 0008) membuat versi dasar secara tidak boleh diubah dan
menyimpan lampiran bagi setiap organisasi (key_label, model_pattern,
endpoint, priority — keutamaan yang lebih kecil berjalan lebih awal; lalai
100). Permukaan pentadbir, dikawal oleh kebenaran organisasi policies.manage:
GET /api/organizations/{id}/policies list
POST /api/organizations/{id}/policies create (yaml + attachments)
GET /api/organizations/{id}/policies/drift git-drift status per policy
GET /api/organizations/{id}/policies/{policyId} detail: policy + versions + attachments
PUT /api/organizations/{id}/policies/{policyId} update yaml / enable / active_version / attachments
DELETE /api/organizations/{id}/policies/{policyId} delete (cascades versions + attachments)
Satah pentadbir mengesahkan sintaks YAML sahaja (kehadiran
kind/apiVersion/steps); kompilasi penuh berlaku apabila gerbang memuatkan
sesuatu versi, jadi dokumen dengan nama pengesan yang tidak diketahui disimpan
tanpa masalah dan gagal secara kelihatan dalam log keputusan. Mutasi dasar
API pentadbir yang berjaya cuba mengemas kini kunci versi dasar organisasi.
Tika gerbang mengkuar kunci itu pada permintaan dan cuba penyegaran stor pada
permintaan seterusnya apabila versi boleh baca berbeza daripada versi cache
yang diketahui. Kunci yang tiada dibaca sebagai versi 0, jadi kunci yang
tiada mencetuskan percubaan itu apabila versi cache diketahui dan bukan sifar.
Apabila kuar versi tidak tersedia, nilai boleh bacanya sama dengan versi cache
(termasuk tiada-sebagai-0 apabila versi cache ialah 0), atau pemuatan stor
yang berjaya tidak menangkap versi, entri cache dipertimbangkan semula untuk
dimuat semula pada permintaan pertama pada atau selepas 30 saat daripada
pemuatan stor dasar yang berjaya terakhirnya. Penyegaran stor yang gagal
mengekalkan entri terakhir yang diketahui baik dan mencuba semula pada
permintaan yang kemudian; ini ialah sandaran yang dipacu permintaan, bukan
tolakan serta-merta atau jaminan data segar semasa stor tidak tersedia.
Pengaktifan atom dan gulung balik
Prasyarat: dasar bagi organisasi diurus melalui API pentadbir di atas atau
yb policies reconcile (§8), dan suis pemati gerbang ialah enforce bagi
tingkah laku penolakan (shadow hanya memerhati). Pengaktifan ialah pergerakan
penunjuk, bukan suntingan kandungan: PUT /api/organizations/{id}/policies/{policyId}
dengan active_version menunjuk saluran kepada satu versi tersimpan yang tidak
boleh diubah; gulung balik ialah panggilan yang sama dengan nombor versi yang
lebih lama. Mutasi yang berjaya menaikkan kunci versi dasar organisasi.
Laluan berjaya: selepas pengaktifan, setiap tika gerbang menyedari kunci yang berubah pada permintaan seterusnya, memuat semula set dasar organisasi, dan menukar salinan terkompilnya dalam satu langkah. Muat semula itu membaca saluran, versi aktif, dan lampiran daripada satu transaksi pangkalan data repeatable-read, jadi set baharu tidak boleh mencampurkan baris yang ditulis pada masa yang berbeza.
Had dan pemulihan kegagalan yang tipikal:
- Satu permintaan, satu petikan. Sesuatu permintaan — termasuk sambungan penstriman dan cubaan semulanya — menggunakan semula petikan yang dimuatkan semasa masuk dan tidak sekali-kali mencampurkan dasar yang dimuatkan sebelum dan selepas pengaktifan. Muat semula dipacu permintaan: tika yang tidak melayan trafik tidak memuat semula.
- Kompil semua-atau-tiada. Muat semula mengkompil keseluruhan set calon organisasi. Satu versi aktif yang tidak sah (rujukan versi yang tergantung, YAML yang tidak boleh dihuraikan, langkah yang tidak diketahui) menolak keseluruhan calon; petikan sebelumnya terus dilayan dan set separa tidak sekali-kali dipasang.
- Pengaktifan semasa muat semula (lumba versi). Gerbang membaca kunci versi sebelum dan selepas bacaan stor. Perubahan di antaranya mencuba semula pemuatan sekali; perubahan sekali lagi menggagalkan penyegaran, petikan sebelumnya terus dilayan, dan permintaan yang kemudian mencuba semula. Oleh itu sesuatu permintaan melihat sama ada set lengkap yang lama atau yang baharu — tidak sekali-kali set pertengahan — tetapi masa pertukaran tidak diselaraskan merentas tika gerbang, jadi tika yang berbeza boleh melayan set lengkap yang berbeza sehingga satu permintaan setiap satu.
- Versi baharu yang tidak berjaya pada organisasi sejuk. Apabila tiada
petikan baik sebelumnya wujud, versi aktif yang tidak sah menjawab
503 policy_configuration_unavailabledalam mod kuatkuasa tanpa mengira tetapan kegagalan sejuk; stor dasar yang tidak tersedia menjawab503 policy_temporarily_unavailablemelainkanYABANIN_POLICY_COLD_FAILURE_MODEialahfail-open. Dalam mod bayang kedua-dua keadaan direkod dan dikira sementara trafik diteruskan tanpa penilaian dasar. Organisasi yang sudah melayan petikan yang baik terus melayannya; kegagalan pemuatan tidak sekali-kali menyingkirkan entri yang boleh digunakan. - Pemulihan. Betulkan pengisytiharan dan gunakan semula, atau gulung balik dengan mengaktifkan versi tidak boleh diubah yang lebih lama; gerbang bertumpu pada permintaan seterusnya. Penumpuan bergantung pada kenaikan versi; apabila kenaikan gagal, sempadan cache 30 saat daripada §8/§9 terpakai sebaliknya.
Kegagalan pemuatan kelihatan sebagai amaran policy load failed dengan kelas
kegagalan (store_read, invalid_config, context_canceled,
runtime_unavailable) dan metrik gateway_policy_load_failures_total (mod ×
keadaan cache: cold = tiada petikan sebelumnya, stale = petikan sebelumnya
terus dilayan).
Log keputusan
Keputusan setiap larian mendarat dalam log keputusan (migrasi 0009,
pengekalan 90 hari): jejak bagi setiap langkah, verdik, id serta versi
dasar, dan cincang kandungan. Bukti dapatan disimpan secara dicincang —
kandungan pengguna yang dipetik tidak sekali-kali kekal di luar pengekalan
bayang/nyahpepijat. Peristiwa analitik membawa medan policy: tatasusunan JSON
rekod keputusan (id/nama/versi dasar, mod, verdik, dapatan
kategori/keterukan/tindakan, tempoh) mengikut tertib pelaksanaan; tiada atau
kosong bermaksud saluran tidak menilai permintaan.
GET /api/organizations/{id}/policy-decisions?page=&page_size=&verdict=&mode=&policy_id=
Metrik
| Siri | Label |
|---|---|
gateway_policy_load_failures_total | mode, cache_state (cold = tiada petikan sebelumnya, stale = petikan sebelumnya terus dilayan) |
gateway_policy_runs_total | policy, endpoint, outcome (allow/flag/mask/deny) |
gateway_policy_denies_total | policy, endpoint |
gateway_policy_masks_total | policy, endpoint |
gateway_policy_shadow_flags_total | policy, endpoint (dapatan yang direkodkan oleh larian bayang) |
gateway_policy_duration_ms | policy, endpoint |
Ditambah pipeline_llmjudge_duration_seconds{model,outcome},
pipeline_llmjudge_verdicts_total{model,outcome} dan keluarga
pipeline_callout_*. Kandungan muatan, kategori atau keterukan tidak
sekali-kali menjadi nilai label.
10. Rujukan persekitaran
| Pemboleh ubah | Lalai | Maksud |
|---|---|---|
YABANIN_POLICY_MODE | off | Suis pemati: off / shadow / enforce (§2). |
YABANIN_POLICY_COLD_FAILURE_MODE | fail-closed | Organisasi sejuk (tiada petikan dasar yang berjaya) semasa stor tidak tersedia: fail-closed menolak dengan 503, fail-open diteruskan tanpa penilaian dasar. Konfigurasi dasar yang tidak sah sentiasa menolak dalam mod kuatkuasa (§9). |
YABANIN_POLICY_CALLOUT_ALLOW_HOSTS | kosong | Corak hos yang dipisahkan koma yang boleh didail oleh langkah panggilan keluar; kosong menyahdayakan langkah panggilan keluar sepenuhnya. |
Lalai awalan penstriman (64 token / 500 ms) ialah parameter dasar pada lampiran
stream_prefix, bukan tombol persekitaran.