რეფერენდუმის განხორციელება

1) მიზნები, საზღვრები და პრინციპები

1. მიეცით ოქმის/დავის ცალსახა ინტერპრეტაცია.

2. დამოუკიდებელი თავსებადობის შემოწმების უზრუნველყოფა.

3. მიუთითეთ კლიენტის/სერვერის/ვებჰუკის სამუშაო მაგალითები.

4. ინტეგრაციისა და განხორციელების ღირებულების შემცირება.

• RI ფოკუსირებულია ქცევითი სისწორეზე და არა მაქსიმალურ შესრულებაზე.
• მოიცავს მინიმალური პროდუქტების პარამეტრებს (TLS, ლოგიკა, მეტრიკა, ტრეისი, შეზღუდვები).
• იგი არ ცვლის კომერციულ/პროდუქტის განხორციელებას, მაგრამ ადგენს „ხარისხის ქვედა ზღვარს“.

• Spec-first: ჭეშმარიტება - სპეციფიკაციებში (OpenAPI/AsyncAPI/Proto/JSON-Schema/IDL).
• Deterministic & Testable: რეპროდუქციული პასუხები და ფიქსაცია.
• Docs-as-Code: ყველაფერი VCS- ში, ერთი ვერსია კოდით და კონფორმაციის ტესტებით.
• Portability: კონტეინერები, Helm/compose, მზა მანიფესტები.

2) რეფერენდუმის განხორციელების ტიპები

RI-Server: სპეციფიკაციის სერვერის სტანდარტი (REST/gRPC/GraphQL/Streaming).
RI-Client/SDK: კლიენტის სტანდარტი (ერთი ან ორი პოპულარული პლატფორმა) + მაგალითები.
RI-Webhook Receiver: ხელმოწერილი ვებჰუკების დამუშავება (ხელმოწერის გადამოწმება, ხელახალი რეგისტრაცია).
RI-Adapters: გადამყვანები შეტყობინებების ბროკერებზე/მოვლენების საბურავებზე (Avro/Proto/JSON, Schema Registry).
RI-Data: საცნობარო ნაკრები, კონფიდენციალურობის პროფილები, „ოქროს“ სნაიპერები.

3) საცავის არქიტექტურა RI

ri/
specs/# OpenAPI/AsyncAPI/Proto/JSON-Schema server/# reference server src/
config/
docker/
helm/
client/# reference client/SDK + examples js/python/go/
conformance/# conformance runner, test cases, gold cases files/
fixtures/
golden/
samples/# end-to-end scripts, Postman/k6/Locust security/# test keys, policies, example signature docs/# manual, ADR, runbook, FAQ ci/# pipelines, configs, compatibility matrix tools/# generators, linters, circuit checkers

• თითოეული გამოცემა 'vX'. Y.Z 'და არტეფაქტები (სურათები, ჩარტები, SDK).
• თითოეული სპეკისთვის - თანხა და ხელმოწერა (supply-chain).
• CHANGELOG აღნიშნავს „დარღვევის“ ცვლილებებს.

4) სპეკები, კონტრაქტები და სქემები

ტრანსპორტი: OpenAPI/REST, gRPC/Proto, GraphQL SDL, AsyncAPI.
სემანტიკა: შეცდომების კოდი, idempotence, კურსორები/პაგინაცია, რეტრაები, დედუპლიკაცია.
მოვლენები: ტიპი/ვერსია, 'id', 'occurred _ at _ utc', 'partition _ key ", შეკვეთის ინვარიანტები.
ხელმოწერები/უსაფრთხოება: OIDC/JWT სტიგმები, ვებჰუკების ხელმოწერა (HMAC/EdDSA), კლავიშების როტაცია.
Compatibility სქემები: წესები 'backward' forward 'full', MAJOR- ის გარეშე დარღვევების აკრძალვა.

5) კონფორმირების ტესტირება

• სპეკებთან შესაბამისობა (სქემების შესაბამისობა),
• ქცევითი ინვარიანტები (idempotence, დახარისხება, კურსორები, TTL, retry პოლიტიკა),
• უსაფრთხოება (ხელმოწერები, ვადები, nonce/replay დაცვა),
• დროებითი ასპექტები (UTC, RFC339, DST),
• უარყოფითი შემთხვევები და სასაზღვრო პირობები.

ოქროს ფაილები: სტაბილური საცნობარო პასუხები/მოვლენები, რომელთა წინააღმდეგაც შედარებულია შედეგები.

python def run_conformance(target_url, cases, golden_dir):
for case in cases:
req = build_request(case. input)
res = http_call(target_url, req)
assert match_status(res. status, case. expect. status)
assert match_headers(res. headers, case. expect. headers)
assert match_body(res. json, golden_dir / case. id, allow_extra_fields=True)
for invariant in case. invariants:
assert invariant. holds(res, case. context)

consumer/sdk-js 1. 4server 1. 6, 1. 7server 2. 0 consumer/sdk-go 0. 9server 1. 5–1. 7   –
webhook-receiver 1. 1events v1events v2 (deprecated fields removed)

6) წარმოების მინიმუმი (ექსცესების გარეშე)

უსაფრთხოება: TLS by default, უსაფრთხოების სათაურები, CORS შეზღუდვა, შეზღუდვები, ანტი-რეპლეი.
Observability: logs (სტრუქტურული + შენიღბვა PD), მეტრიკა (p50/p95/p99, error rate), ტრეისი (კორელაცია 'request _ id').
Config: ყველაფერი გარემო ცვლადის და ფაილების საშუალებით, კონფიგურაციის სქემა დალაგებულია.
Perf bandline: ჯანსაღი ტყვიის პარამეტრები, ჯაჭვის ტაიმუტის ბიუჯეტი, ქეში.
სტაბილურობა: გადატვირთვა ჯიტერთან, circuit breaker, backpressure.

7) CI/CD და არტეფაქტები

1. ლინტი/ასამბლეა/ერთეულის ტესტები.

2. სპეკის ალბათობა (OpenAPI/AsyncAPI/Proto-lint).

3. SDK/spikes სტაბილურობა.

4. კონფორმირების რანგი: 'ri-server' წინააღმდეგ 'cases' და „ოქროს“ წინააღმდეგ.

5. სურათების შეკრება (SBOM, ხელმოწერა), გამოქვეყნება რეესტრში.

6. E2E სცენარები (docker-compose/kind/Helm).

7. საიტისა და მაგალითების გამოქვეყნება.

• კონტეინერის სურათები 'ri-server', 'ri-webhook',
• SDK პაკეტები (npm/pypi/go),
• Helm სქემა/კომპოზიციის ფაილები,
• zip „ოქროს ფაილებით“ და კონფორმული რანერით.

8) ნიმუშები, SDK და „როგორ“

მინი პროგრამა ორ პოპულარულ დასტაში (მაგ., Node. js/Go) ნაბიჯებით: API- ს ავთენტიფიკაცია - ზარი, შეცდომების დამუშავება - retrai - ვებჰუკი.
როგორ: idempotent POST, კადრების პაგინაცია, ვებჰუკის ხელმოწერა, 429/503 დამუშავება.
k6/JMeter პროფილები „smoke პერფისთვის“ (არა დატვირთვა, არამედ ძირითადი ჯანმრთელობა).

9) ვერსია და ევოლუცია

SemVer: დარღვევის ცვლილებები MAJOR; დამატებები შეფერხების გარეშე: MINOR; შესწორებები PATCH.
დეპრესიის გეგმა: გამოცხადება სპექტაკლებში, ფერფლის დროშები, „ჩრდილის“ კონფიგურაციის რეჟიმის პერიოდი, შემდეგ enforce.
მოვლენების თავსებადობა: კონსიუმერები ვალდებულნი არიან უგულებელყონ უცნობი სფეროები.

10) უსაფრთხოება და კონფიდენციალურობა RI- ში

ტესტის გასაღებები და საიდუმლოებები - მხოლოდ სტენდისთვის; დოქებში - ჩანაცვლების ინსტრუქცია.
PD- ის შენიღბვა ლოგებში; ფიქსატორების ანონიმიზაციის პროფილები (PII - სინთეზური).
დემო გარემოს არტეფაქტების ცხოვრების პოლიტიკა (TTL, გამწმენდი მანქანები).

11) დაკვირვება და SLO RI- სთვის

SLI/SLO RI: p95 <250 ms მითითებულ სტენდზე, error rate <0. 5%, სწორი დეგრადაცია დამოკიდებულების უკმარისობის ქვეშ (ნიმუშში).
დაშბორდები: latency/Throughput/Errors + კონფორმაციის შედეგები.
Decision-logs webhuks/token- ის შემოწმების ხელმოწერის მიზნით (უარის თქმის კვალიფიციური მიზეზები).

12) პროდუქტიულობა: „საკმარისი“ ბაზლაინი

პროფილები 'wrk/hey/k6 „ცხელი“ და „ცივი“ გზებზე.
მკაფიო პოზიცია: RI არ კონკურენციას უწევს მაქსიმალურ RPS- ს, მაგრამ უნდა გაუძლოს ტიპურ მიზანს (მაგალითად, 500 RPS t3). medium ერთად r95 <200ms) - როგორც სახელმძღვანელო ინტეგრატორებისთვის.

13) ოპერაციის სახელმძღვანელო (runbook)

ადგილობრივი გაშვება: კომპოზიცია/' make up '.
K8s deploy: Helm მნიშვნელობები, საიდუმლოებები, ინგრედიენტები, HPA.
Webhuks- ის ხელმოწერის გასაღებების როტაცია (ორმაგი კეი პერიოდი).
Trablschuting: ხშირი შეცდომები და მათი მიზეზები (401, 403, 429, 503), როგორ წაიკითხოთ logs/traces.

14) მართვა და საკუთრება

Owners: სპეკის პროდუქტის მფლობელი + პლატფორმა (ტექნიკა) + უსაფრთხოება.
გამოშვების კალენდარი და დამანგრეველი ცვლილებების კოორდინაციის ფანჯარა.
RFC/ADR ოქმების მნიშვნელოვან ცვლილებებზე.

15) ადაპტაცია ენებზე/პლატფორმებზე

რეკომენდებულია მინიმალური: ერთი მაღალი დონის (JS/TS) და ერთი სისტემური (Go/Java).
Mapping ტიპები: როგორ არის წარმოდგენილი თარიღები/ფულადი ფორმატები/decimal/ბაიტის ნაკრები.
რეკომენდაციები retrays/taimautam/აუზის პარამეტრების შესახებ თითოეულ SDK- ში.

16) ანტი შაბლონები

RI = „ქვიშის ყუთი ტესტების გარეშე“: არ არსებობს კონფორმაცია, არ არსებობს სარგებელი.
სპეკა „ცხოვრობს ცალკე“ კოდიდან და ტესტებიდან - შეუსაბამობა.
„ოქროს ფაილების“ და ინვარიანტების არარსებობა - ფლეიკა და ქცევასთან დაკავშირებული დავები.
ჩარჩო დამოკიდებულება: მკაცრი აკავშირებს ერთ ბიბლიოთეკას/ღრუბელს კონტეინერის გარეშე.
ლოგოები შენიღბვის გარეშე PD, გასაღებები საცავებში.
პერფ მიქსები ქცევის ნაცვლად: მცდელობა გაზომოს „ვინ უფრო სწრაფია“ ნაცვლად „ვინ არის სწორი“.
ერთი გიგანტური ბინარი/გამოსახულება მოდულარობისა და არტეფაქტების გარეშე (SDK/ჩარტები/სპეკები).

17) არქიტექტორის ჩეკის სია

1. სპეკა კანონიკური და ვალიდურია? (OpenAPI/Proto/AsyncAPI/JSON-Schema)

2. არსებობს RI სერვერი და მინიმუმ ერთი RI-client/SDK სრული მაგალითებით?
3. მზად არის კონფორმანსის რანერი, საქმეები, ოქროს ფაილები, ნეგატივები და ინვარიანტები?
4. CI/CD აგროვებს სურათებს, SDK, საიტს, იწყებს კონფიგურაციას და e2e?
5. ნაგულისხმევი უსაფრთხოება: TLS, ხელმოწერები, ლიმიტები, შენიღბვა?
6. დაკვირვება: ლოგოები/მეტრიკა/ტრეისი, დაშბორდები და SLO RI- სთვის?
7. Perf ბაზლაინი დოკუმენტირებულია და ასახავს?
8. SemVer- ის ვერსია, თავსებადობის მატრიცა, დეპრესიის პროცედურა?
9. Runbook და ადგილობრივი/კლასტერული გაშვება - ერთ დაწკაპუნებაში?
10. განსაზღვრულია თუ არა მფლობელები, გამოშვების კალენდარი, RFC/ADR ნაკადი?

18) მინი მაგალითი: რეფერენდუმი-ვებჰუკი (ფსევდოკოდი)

python def verify_webhook(request, keys):
sig = request. headers["X-Signature"]
ts = int(request. headers["X-Timestamp"])
if abs(now_utc(). epoch - ts) > 300: return 401 # replay window body = request. raw_body if not any(hmac_ok(body, ts, k, sig) for k in keys. active_and_previous()):
return 401 event = json. loads(body)
if seen(event["id"]): return 200 # idempotency handle(event)
mark_seen(event["id"])
return 200

ტესტის შემთხვევა ამოწმებს: დროის ფანჯარა, ხელმოწერის სისწორე (მიმდინარე და წინა გასაღები), ღონისძიების იდემპოტენტურობა. id ', ნეგატივები (გაფუჭებული ხელმოწერა, ვადაგასული' ts ').

დასკვნა

რეფერენდუმის განხორციელება სისტემის ქცევის კანონია: კოდით, ტესტებითა და არტეფაქტებით დადასტურებული ერთიანი სპეკა. კარგი RI აჩქარებს ინტეგრაციას, ასუფთავებს ოქმების ორაზროვნებას, უზრუნველყოფს დამოწმებულ თავსებადობას და ადგენს უსაფრთხოების, დაკვირვებისა და შესრულების მინიმალურ სტანდარტებს. გახადეთ იგი თქვენი საინჟინრო „ჩონჩხის“ ნაწილი - და თქვენი პროდუქტები, პარტნიორები და ეკოსისტემა სწრაფად და საიმედოდ გადაადგილდება.