Files
Gnuboard7/tests/scenarios/extension-declarative-middleware.yaml
T
HeuJung c0e0d82459 refactor(extension): 확장 미들웨어 선언적 self-gate 정규화
확장이 SP Kernel 미들웨어 그룹을 직접 조작하거나 라우트 파일에 미들웨어
FQCN 을 직접 부착하던 임시 방식을, 확장이 부착 대상(targets)을 명시 선언하고
코어가 요청 시점에 라우트명·URI 로 매칭해 실행하는 self-gate 로 정규화.
번들 7건(ecommerce/gdpr/pay 3종) 이전, audit 룰 3건·문서·버전 동기화 동반.

부수적으로 generate-skills.cjs 가 재생성 시 신의성실(부수의무) 섹션을 소실
시키던 회귀를 수정 — 스킬별 불릿을 스크립트 SSoT 로 편입해 재생성에도 보존.
2026-07-16 10:22:51 +09:00

90 lines
5.3 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# audit:allow test-scenario-coverage reason: axes cross product(extension_type×group×timing×target_kind×extension_status×route_match = 256)는 조합 열거로, 실질 회귀 가드는 effects 가 담당한다. effects 는 test_files 의 메서드 docblock @effects 로 전수 매핑되어 개별 검증된다. target_kind 8종 매칭식·group 펼침·timing 분리·활성 필터·라우트명 vs URI 매칭은 registry 단위 테스트가 값별로 직접 관측하고, 게이트 실행/무명 라우트/실요청 파싱은 gate 테스트가 커버한다. 조합 개별 docblock 마킹은 effects 매핑과 중복이므로 생략.
feature: 확장 선언 미들웨어 self-gate (getMiddleware + ExtensionMiddlewareGate)
description: |
확장(모듈/플러그인)이 getMiddleware() 로 선언한 미들웨어를 코어가 요청 시점에
대상 매칭으로 실행하는 self-gate 아키텍처.
핵심 동작:
- AbstractModule/AbstractPlugin::getMiddleware() 가 [class, groups, timing, targets]
배열을 선언 (기본 []). interface 가 아닌 Abstract 에만 정의 — registry 는
method_exists 로 게이트.
- ExtensionMiddlewareRegistry 가 활성 확장의 선언을 수집해 [group.timing => 술어]
인덱스로 캐시. targets 는 술어(op=name|name_ext|name_core|uri|always)로 정규화.
- 코어 ExtensionMiddlewareGate 래퍼가 bootstrap 에서 web/api × before_core/after_core
로 4회 등록. 요청 시점에 라우트명·URI 를 술어와 대조해 매칭 미들웨어만 Pipeline 실행.
- 무명 SSR 셸 catch-all 대응: routeName='' 이어도 URI 패턴(op=uri)·everything(op=always)
술어는 매칭. 라우트명 계열(op=name*)은 무명에서 miss.
- 인덱스는 확장 활성/비활성/설치/제거/리로드 시 ExtensionMiddlewareRegistry::flush()
로 무효화 (Module/PluginManager 상태 변경 지점).
targets 카탈로그 (target_kind 축):
self / all_extensions / core / everything(·*) / module:{id} / plugin:{id} /
원시 라우트명 glob / brace / URI 패턴('/' 시작).
정밀도 (pay IP 화이트리스트):
self 로 뭉치지 않고 webhook 라우트명만 정밀 타게팅해 브라우저 콜백(payment.callback)에는
IP 가드가 부착되지 않도록 한다 — 결제 회귀 방지.
axes:
extension_type: [module, plugin]
group: [web, api]
timing: [before_core, after_core]
target_kind: [self, all_extensions, core, everything, module_id, plugin_id, glob, brace, uri]
extension_status: [active, inactive]
route_match: [hit, miss]
exclusions:
- { extension_status: inactive, route_match: hit, reason: "비활성 확장은 registry 인덱스에서 제외 → 어떤 라우트도 hit 불가" }
effects:
# registry 매칭 (target_kind 값별)
- self_target_expands_to_own_extension_prefix_per_group
- all_extensions_matches_extension_routes_only
- core_target_matches_core_routes_only_negative_predicate
- everything_and_star_match_all_routes_including_unnamed
- module_id_and_plugin_id_target_scope_to_that_extension
- raw_glob_target_matches_route_name
- brace_target_expands_to_or_of_names
- uri_pattern_target_matches_path_not_route_name
# groups / timing / 검증
- groups_array_expands_to_per_group_entries
- empty_or_disallowed_groups_declaration_is_rejected
- missing_targets_declaration_is_rejected
- nonexistent_middleware_class_is_skipped
- before_core_and_after_core_timing_are_separated
- default_timing_is_after_core
- inactive_extension_is_excluded_from_index
- flush_rebuilds_index
# 게이트 실행
- gate_runs_matched_middleware_via_pipeline
- gate_passes_through_when_no_match
- gate_matched_middleware_can_short_circuit_response
- gate_execution_order_follows_matched_list
- gate_reaches_registry_and_runs_matched_for_unnamed_route
- gate_param_string_parses_group_and_timing_on_real_request
# 번들 이전 정밀도
- detect_device_declared_and_resolved_for_root_uri_web_only
- pay_ip_guard_matched_for_webhook_routes
- pay_ip_guard_not_matched_for_browser_callback
- gdpr_cookie_consent_declared_everything_before_core
test_files:
- tests/Feature/Extension/ExtensionMiddlewareRegistryTest.php
- tests/Unit/Http/Middleware/ExtensionMiddlewareGateTest.php
- tests/Feature/Extension/ExtensionMiddlewareGateIntegrationTest.php
- modules/_bundled/sirsoft-ecommerce/tests/Unit/Providers/DetectDeviceMiddlewareRegistrationTest.php
- plugins/_bundled/sirsoft-pay_nhnkcp/tests/Feature/Middleware/RestrictKcpIpTest.php
- plugins/_bundled/sirsoft-pay_kginicis/tests/Feature/Middleware/InicisNotifyIpWhitelistGateTest.php
- plugins/_bundled/sirsoft-pay_nicepayments/tests/Feature/Middleware/VbankNotifyIpWhitelistGateTest.php
- plugins/_bundled/sirsoft-gdpr/tests/Unit/PluginMiddlewareDeclarationTest.php
rules_layer_coverage:
- rule: extension-middleware-declarative-registration
coverage: 번들 SP 의 Kernel 미들웨어 그룹 직접 조작 금지 — 이전 후 무검출, 이전 전 패턴 검출로 회귀 가드
- rule: extension-route-middleware-alias-reference
coverage: 번들 라우트 파일의 자기 미들웨어 FQCN 부착 금지 — 동일
- rule: extension-middleware-gate-cache-coverage
coverage: Abstract 에 getMiddleware 존재 시 Manager 에 registry flush 존재 — 배치 완전성은 flush_rebuilds_index effect 가 병행