2nd/10_Wiki/Topics/Architecture/System_Protocol_Standard.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-system-protocol-standard	System Protocol Standard	10_Wiki/Topics	verified	self	Protocol Standardization Wire Protocol Design Interface Standards	none	A	0.85	applied	protocol standard interoperability design		2026-05-10	pending	language framework multi protobuf-grpc

System Protocol Standard

매 한 줄

"매 system 간 wire-level contract 의 versioned, versionable specification". 매 protocol standard 의 — message format + transport + semantics + evolution rules. 2026 의 modern stack 의 protobuf + gRPC + OpenAPI + AsyncAPI 의 dominant.

매 핵심

매 components of protocol spec

• Syntax: 매 wire format (binary, JSON, XML).
• Semantics: 매 message meaning + state machine.
• Transport: TCP, UDP, HTTP/2, QUIC, WebSocket.
• Versioning: 매 backward / forward compat rules.
• Error model: 매 status codes, retry semantics.

매 design 원칙

• Forward compat: 매 old client 의 new server 의 read.
• Backward compat: 매 new client 의 old server 의 read (graceful).
• Self-describing: 매 schema 의 embed (JSON-Schema, protobuf descriptor).
• Idempotency: 매 retry 의 safe.
• Explicit versioning: 매 URL /v1/, header, or schema apiVersion.

매 standard families

• RPC: gRPC, Thrift, Cap'n Proto, JSON-RPC.
• REST: HTTP + OpenAPI 3.1.
• Message: AMQP, MQTT, Kafka wire, NATS, AsyncAPI 3.0.
• Streaming: WebRTC, RTSP, HLS, WebTransport.

매 응용

1. Microservice contracts.
2. IoT device protocols.
3. Inter-org B2B (EDI → modern API).
4. Embedded → cloud telemetry.

💻 패턴

Protobuf — versionable schema

syntax = "proto3";
package order.v1;

message Order {
  string id = 1;
  string customer_id = 2;
  repeated LineItem items = 3;
  google.protobuf.Timestamp created_at = 4;
  reserved 5, 6;            // burned fields — never reuse
  reserved "deprecated_field";
}

message LineItem {
  string sku = 1;
  int32 qty = 2;
  Money price = 3;
}

gRPC service contract

service OrderService {
  rpc Create(CreateOrderRequest) returns (Order);
  rpc Get(GetOrderRequest) returns (Order);
  rpc Stream(StreamOrdersRequest) returns (stream Order);
}

OpenAPI 3.1 — REST contract

openapi: 3.1.0
info:
  title: Order API
  version: 1.4.0
paths:
  /v1/orders/{id}:
    get:
      operationId: getOrder
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }

Versioning — semver + deprecation

GET /v1/orders/123
Sunset: Wed, 01 Jan 2027 00:00:00 GMT
Deprecation: true
Link: </v2/orders/123>; rel="successor-version"

Schema evolution rules (protobuf)

ALLOWED:
  - Add new optional field (new tag #)
  - Rename field name (tag # is contract)
  - Add new RPC

FORBIDDEN:
  - Change tag #
  - Change field type (int32 → string)
  - Make optional → required
  - Reuse reserved tag

Error model — gRPC + RFC 7807

message Error {
  string code = 1;       // RESOURCE_NOT_FOUND
  string message = 2;
  string trace_id = 3;
  google.protobuf.Any details = 4;
}

// REST RFC 7807
{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient funds",
  "status": 422,
  "detail": "Account balance is $5; tried to withdraw $100",
  "instance": "/accounts/12345/withdraw"
}

AsyncAPI — event protocol

asyncapi: 3.0.0
info: { title: Order Events, version: 1.0.0 }
channels:
  order.created:
    address: order.v1.created
    messages:
      OrderCreated:
        payload:
          $ref: '#/components/schemas/Order'

매 결정 기준

상황	Approach
Internal microservice, polyglot	gRPC + protobuf
Public API	REST + OpenAPI 3.1
Browser real-time	WebSocket / WebTransport
Event-driven	AsyncAPI + Kafka/NATS
Embedded / IoT	MQTT + protobuf

기본값: 매 protobuf + gRPC (internal), 매 OpenAPI + JSON (external).

🔗 Graph

• 부모: API Design · Distributed Systems
• 변형: gRPC · REST
• 응용: Microservices
• Adjacent: Backward Compatibility · Idempotency

🤖 LLM 활용

언제: schema generation, migration plan (v1 → v2), client SDK scaffolding. 언제 X: final wire format approval (security/perf review 의 human).

❌ 안티패턴

• No versioning: 매 v1 의 미래 의 painful breaking change.
• Reuse reserved tags: 매 silent data corruption.
• Required fields in proto3: 매 forward-compat 의 break.
• Stringly-typed enums: 매 typo + drift — 매 enum 의 사용.
• "Dump it all": 매 message 의 too-fat — 매 Single Responsibility 의.

🧪 검증 / 중복

• Verified (Google API Design Guide; gRPC docs; OpenAPI 3.1; RFC 7807).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — protobuf, OpenAPI, AsyncAPI, versioning rules