Skip to main content

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:

CangkukJenis muatanTercetus
pre_upstreamrequestsebelum panggilan huluan
post_upstreamresponseselepas respons huluan
stream_prefixstream_prefixawalan strim tertimbal (lihat §7)
stream_finalstream_finalagregat strim penuh
tool_pretool_argssebelum panggilan alat/MCP
tool_posttool_resultselepas 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):

NilaiTingkah laku
offmasa jalan tidak sekali-kali dibina; setiap cangkuk ialah no-op (lalai)
shadowsetiap dasar diturunkan kepada bayang semasa masa kompil
enforcedasar 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:

MedanMaksud
whensumber syarat pilihan (§4); dikompil sekali semasa pemuatan dasar
when_enginesemat enjin syarat (expr/lua/starlark); wajib sebaik sahaja lebih daripada satu enjin didaftarkan
timeoutbajet bagi setiap langkah, sintaks tempoh Go (50ms, 2s); tamat masa mengikut on_error
on_errorfail_closed (lalai; kegagalan menolak dan memintas litar) | fail_open | fail_open+flag (menambah dapatan bendera step_error sintetik)
parallelid 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
paramsparameter 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 menyemat request).
  • action — tindakan yang dibawa dapatan langkah: flag (lalai), mask atau deny (allow bukan tindakan pengesan). Kegagalan pengesahan kilang ialah ralat pemuatan dasar.

Pengesan​

LangkahKategoriParameter (selain yang biasa)
builtin/national-piiinnsnils, pan, ru_passport, ogrn + nombor identiti BR/IN/MY/AE/ZA/NG/KE/EG— (set RU tetap + 9 bidang kuasa; disahkan checksum/Luhn)
builtin/secretssecret (+ nilai JSON berkunci kelayakan)— (bentuk kunci penyedia, pengepala PEM, bentuk JWT; bukti tidak sekali-kali dipetik — [REDACTED_SECRET])
builtin/injectioninjection— (frasa suntikan gesaan RU + EN)
builtin/word-countword_countmin, max (sekurang-kurangnya satu batas wajib; max 0 = tanpa batas)
builtin/char-countchar_countmin, max (rune, bukan bait)
builtin/sentence-countsentence_countmin, max (heuristik penamat luar talian)
builtin/containscontainswords (senarai wajib), mode any|all|none (lalai any), case_insensitive (lalai true)
builtin/regexregexpattern (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-schemajson_schemaschema (Skema JSON sebaris wajib; dikompil semasa pemuatan)
builtin/json-keysjson_keyskeys (laluan bertitik wajib), mode any|all|none (lalai all)
builtin/url-checkurlschemes (lalai ["https","http"]), allow_hosts, deny_hosts (kad liar *.suffix); sepenuhnya luar talian — tidak sekali-kali mengambil
builtin/code-detectcode.<lang>languages (subset sql|python|typescript, lalai semua)
builtin/languagelanguageallowed (subset tidak kosong yang wajib daripada ru|en|other; heuristik dominasi skrip)
builtin/model-whitelistmodelmodels (corak glob wajib; model tidak diketahui/kosong = pelanggaran)
builtin/metadata-requiredmetadatakeys (medan/label meta) dan/atau labels (pasangan label=nilai); sekurang-kurangnya satu wajib

Mutator​

LangkahKesanParameter
builtin/redactmenggantikan 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/pseudonymizepseudonimisasi boleh balik: rentang menjadi alias {{YPP_n}} yang stabil; penggantian mengalir keluar sahaja — tiada penggantian songsang ke dalam responscategories, patterns, carry none (lalai)|session, max_input
builtin/header-rewritemenyunting pengepala permintaan huluan (pembuangan dikenakan sebelum set; suntikan CRLF/NUL ialah ralat pemuatan)set (peta), remove (senarai); permintaan sahaja
builtin/model-rewritemenulis semula model permintaan (jahitan sempadan data: halakan permintaan yang membawa PII kepada model dalam rantau); setiap tulis semula direkodkan sebagai dapatan bendera model_rewriteto (wajib), from (prasyarat pilihan); permintaan sahaja
builtin/partials-substitutemenggantikan 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:

  1. Lalai strim. Apabila masa jalan dasar aktif dalam mod penguatkuasaan dan sesuatu dasar dilampirkan pada stream_prefix, builtin/redact atau builtin/pseudonymize tanpa kinds menyertakan stream_prefix secara lalai. Lalai tanpa kinds yang sama menyertakan stream_final apabila cangkuk itu dilampirkan; senarai kinds yang eksplisit menyempitkan skop langkah. Ini ialah lalai biasa yang sama seperti yang diterangkan dalam §5. stream_final memeriksa strim yang telah selesai selepas pengeluaran dan tidak boleh menghalang atau menarik balik bait yang sudah dihantar.
  2. Pintu awalan dan bawaan ketulan. Apabila dasar stream_prefix dilampirkan, 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_tokens atau prefix_delay_ms boleh 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.
  3. Tolak awalan. deny daripada petikan awalan membatalkan aliran sebelum sebarang bait yang ditahan dilepaskan; gerbang menghantar bingkai ralat kanonik dan data: [DONE].
  4. Jika output tidak berubah. Semak bahawa masa jalan dasar didayakan dalam mod penguatkuasaan, dasar dilampirkan pada organisasi, model, endpoint dan cangkuk stream_prefix yang dimaksudkan, dan senarai kinds yang eksplisit tidak mengecualikan stream_prefix. Semak bahawa sasaran sintetik yang lengkap tiba dalam awalan yang ditangkap sebelum ia disiram. Betulkan lampiran atau kinds, 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.
  5. Semakan akhir. Bingkai yang telah dihantar terkumpul menjadi dokumen chat.completion sintetik, yang diperiksa oleh dasar stream_final selepas pengeluaran. deny akhir 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 reconcile merancang perbezaan (dry-run secara lalai); --apply menumpu 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 DRIFT dalam pelan dan ditimpa oleh versi baharu semasa digunakan (versi tidak boleh diubah, jadi tiada apa-apa yang dimusnahkan). API pentadbir GET /api/organizations/{id}/policies/drift melaporkan status bagi setiap dasar managed / drift / unmanaged tanpa 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_unavailable dalam mod kuatkuasa tanpa mengira tetapan kegagalan sejuk; stor dasar yang tidak tersedia menjawab 503 policy_temporarily_unavailable melainkan YABANIN_POLICY_COLD_FAILURE_MODE ialah fail-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​

SiriLabel
gateway_policy_load_failures_totalmode, cache_state (cold = tiada petikan sebelumnya, stale = petikan sebelumnya terus dilayan)
gateway_policy_runs_totalpolicy, endpoint, outcome (allow/flag/mask/deny)
gateway_policy_denies_totalpolicy, endpoint
gateway_policy_masks_totalpolicy, endpoint
gateway_policy_shadow_flags_totalpolicy, endpoint (dapatan yang direkodkan oleh larian bayang)
gateway_policy_duration_mspolicy, 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 ubahLalaiMaksud
YABANIN_POLICY_MODEoffSuis pemati: off / shadow / enforce (§2).
YABANIN_POLICY_COLD_FAILURE_MODEfail-closedOrganisasi 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_HOSTSkosongCorak 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.