DefStream 0.1.9__tar.gz → 0.1.11__tar.gz

{defstream-0.1.9 → defstream-0.1.11}/DefStream.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DefStream
-Version: 0.1.9
+Version: 0.1.11
 Summary: Synchronous message processing with pluggable broker adapters
 Home-page: https://github.com/yong5eon/DefStream
 Author: Heo Yongseon
@@ -545,13 +545,14 @@ class Add(
     schema=request_schema,
     validator=request_validator,
     example={'a': 10, 'b': 20},
-    description='Add two integers',
   ),
   response=Specification(
     schema=response_schema,
     validator=response_validator,
     example=30,
   ),
+  name='add',
+  description='Add two integers',
 ):
   def run(
     self,
@@ -568,6 +569,10 @@ class Add(
 - 일반 JSON Schema 딕셔너리와 직접 작성한 검증 함수도 각각 `schema`, `validator`에 전달할 수 있습니다.
 - `example`은 문서용 값이며 자동 실행·검증하지 않습니다.
 - `format`의 기본값은 `application/json`입니다. 문서의 미디어 타입만 바꾸며 브로커 코덱은 별도 설정입니다.
+- Run의 `name`은 AsyncAPI Operation 키와 Metrics 작업 키에 함께 사용합니다.
+  생략하면 `모듈명.__qualname__`을 사용하며, Run의 `description`은 AsyncAPI Operation에 표시됩니다.
+  명시적 이름은 `[A-Za-z0-9_.-]+` 형식이며 공백·한국어는 허용하지 않습니다.
+  대소문자와 입력값을 그대로 보존합니다.
 - 실행 순서는 초기화 훅 → 요청 검증 → `run()` → 응답 검증 → 완료 훅 → 응답 발행·ACK입니다.
 
 검증 예외는 작업 실패로 처리되어 오류 훅과 `on_error` 정책을 따릅니다.

{defstream-0.1.9 → defstream-0.1.11}/DefStream.egg-info/SOURCES.txt

@@ -18,6 +18,9 @@ issues/feature/8/IMPLEMENTS.md
 issues/feature/8/README.md
 issues/feature/8/REQUIREMENTS.md
 issues/feature/8/ci.refs.json
+issues/fix/10/IMPLEMENTS.md
+issues/fix/10/README.md
+issues/fix/10/REQUIREMENTS.md
 issues/fix/3/IMPLEMENTS.md
 issues/fix/3/README.md
 issues/fix/3/REQUIREMENTS.md

{defstream-0.1.9 → defstream-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DefStream
-Version: 0.1.9
+Version: 0.1.11
 Summary: Synchronous message processing with pluggable broker adapters
 Home-page: https://github.com/yong5eon/DefStream
 Author: Heo Yongseon
@@ -545,13 +545,14 @@ class Add(
     schema=request_schema,
     validator=request_validator,
     example={'a': 10, 'b': 20},
-    description='Add two integers',
   ),
   response=Specification(
     schema=response_schema,
     validator=response_validator,
     example=30,
   ),
+  name='add',
+  description='Add two integers',
 ):
   def run(
     self,
@@ -568,6 +569,10 @@ class Add(
 - 일반 JSON Schema 딕셔너리와 직접 작성한 검증 함수도 각각 `schema`, `validator`에 전달할 수 있습니다.
 - `example`은 문서용 값이며 자동 실행·검증하지 않습니다.
 - `format`의 기본값은 `application/json`입니다. 문서의 미디어 타입만 바꾸며 브로커 코덱은 별도 설정입니다.
+- Run의 `name`은 AsyncAPI Operation 키와 Metrics 작업 키에 함께 사용합니다.
+  생략하면 `모듈명.__qualname__`을 사용하며, Run의 `description`은 AsyncAPI Operation에 표시됩니다.
+  명시적 이름은 `[A-Za-z0-9_.-]+` 형식이며 공백·한국어는 허용하지 않습니다.
+  대소문자와 입력값을 그대로 보존합니다.
 - 실행 순서는 초기화 훅 → 요청 검증 → `run()` → 응답 검증 → 완료 훅 → 응답 발행·ACK입니다.
 
 검증 예외는 작업 실패로 처리되어 오류 훅과 `on_error` 정책을 따릅니다.

{defstream-0.1.9 → defstream-0.1.11}/README.en.md

@@ -481,13 +481,14 @@ class Add(
     schema=request_schema,
     validator=request_validator,
     example={'a': 10, 'b': 20},
-    description='Add two integers',
   ),
   response=Specification(
     schema=response_schema,
     validator=response_validator,
     example=30,
   ),
+  name='add',
+  description='Add two integers',
 ):
   def run(
     self,
@@ -504,6 +505,10 @@ class Add(
 - Plain JSON Schema dictionaries and custom validation functions can also be passed as `schema` and `validator`.
 - `example` is documentation data and is not automatically executed or validated.
 - `format` defaults to `application/json`. It changes documented media types, not broker codecs.
+- Run's `name` is used as both the AsyncAPI Operation key and the Metrics task key.
+  When omitted, `module.__qualname__` is used; Run's `description` appears on the AsyncAPI Operation.
+  Explicit names must match `[A-Za-z0-9_.-]+`; whitespace and Korean characters are not allowed.
+  Names are case-sensitive and preserved exactly as provided.
 - Execution order: setup hooks → request validation → `run()` → response validation → completion hooks → reply/ACK.
 
 Validation exceptions are task failures and follow error hooks and the `on_error`

{defstream-0.1.9 → defstream-0.1.11}/README.md

@@ -512,13 +512,14 @@ class Add(
     schema=request_schema,
     validator=request_validator,
     example={'a': 10, 'b': 20},
-    description='Add two integers',
   ),
   response=Specification(
     schema=response_schema,
     validator=response_validator,
     example=30,
   ),
+  name='add',
+  description='Add two integers',
 ):
   def run(
     self,
@@ -535,6 +536,10 @@ class Add(
 - 일반 JSON Schema 딕셔너리와 직접 작성한 검증 함수도 각각 `schema`, `validator`에 전달할 수 있습니다.
 - `example`은 문서용 값이며 자동 실행·검증하지 않습니다.
 - `format`의 기본값은 `application/json`입니다. 문서의 미디어 타입만 바꾸며 브로커 코덱은 별도 설정입니다.
+- Run의 `name`은 AsyncAPI Operation 키와 Metrics 작업 키에 함께 사용합니다.
+  생략하면 `모듈명.__qualname__`을 사용하며, Run의 `description`은 AsyncAPI Operation에 표시됩니다.
+  명시적 이름은 `[A-Za-z0-9_.-]+` 형식이며 공백·한국어는 허용하지 않습니다.
+  대소문자와 입력값을 그대로 보존합니다.
 - 실행 순서는 초기화 훅 → 요청 검증 → `run()` → 응답 검증 → 완료 훅 → 응답 발행·ACK입니다.
 
 검증 예외는 작업 실패로 처리되어 오류 훅과 `on_error` 정책을 따릅니다.

defstream-0.1.11/issues/fix/10/IMPLEMENTS.md

@@ -0,0 +1,150 @@
+# Run 에 이름(name)과 설명(description) 지원 구현 기록
+
+## 1. 구현 개요
+
+[요구사항](./REQUIREMENTS.md)에 따라 Run 클래스 정의에 `name`과 `description`을
+추가하고, 이름을 AsyncAPI와 Metrics의 작업 식별자로 연결했다. 이름 미지정 시
+`모듈명.__qualname__`을 사용한다. 설명은 AsyncAPI Operation에만 반영한다.
+
+- 구현·검증일: 2026-10-20
+- 사용자용 안내: [변경 로그](./README.md)
+
+## 2. 구현 내용
+
+- [Run](../../../src/Worker/Run.py) 클래스 정의에서 `name`과 `description`
+  키워드를 받는다. `RunMeta`가 이름을 내부 키워드 `run_name`으로 중계하고,
+  `__init_subclass__`가 이름과 설명을 처리한다. 명시적 이름은
+  `[A-Za-z0-9_.-]+` 전체 일치로 검사하고, 설명은 문자열 또는 `None`으로 검증한다.
+- 클래스 생성 시 이름이 생략되면 해당 클래스의 `__module__`과 `__qualname__`으로
+  기본 이름을 만든다. 하위 Run에는 상위 Run의 이름과 설명을 상속하지 않는다.
+- [Worker](../../../src/Worker/Worker.py)는 Run 등록 시 동일한 이름이 이미
+  등록되어 있는지 검사하고 중복을 `ValueError`로 거부한다. 메시지를 Metrics에
+  전달하는 식별자도 `run.name`을 사용한다.
+- [Specifications](../../../src/Inspector/Extensions/Specifications.py)은
+  `operations` 키에 `task.name`을 사용하고, 지정된 `task.description`을 해당
+  Operation에 기록한다. 문서 생성 시에도 중복 Operation 키를 거부한다.
+- [Metrics](../../../src/Inspector/Extensions/Metrics.py)는 초기 작업 통계 맵의
+  키를 `task.name`으로 만들며, 중복 키를 발견하면 통계 맵을 부분 초기화하지 않고
+  `ValueError`를 발생시킨다.
+- [Specification](../../../src/Worker/Specification.py)에서 `description` 인자와
+  AsyncAPI 메시지 설명 생성을 제거했다. schema, validator, example, format은
+  유지한다.
+- [RabbitMQ Worker 샘플](../../../sample/Worker/RabbitMQ/Tasks.py)과
+  [Redis Worker 샘플](../../../sample/Worker/Redis/Sample.py)에 `add`, `divide`
+  이름 및 작업 설명을 지정했다. RabbitMQ 샘플의 request·response
+  Specification 설명은 Run의 메타데이터로 옮겼다.
+- [한국어 사용 설명서](../../../README.md)와
+  [영어 사용 설명서](../../../README.en.md)에 새 선언 방법을 반영했다.
+
+## 3. 사용 방법
+
+```python
+from DefStream.Worker import Run, Specification
+
+
+class Add(
+  Run,
+  name='add',
+  description='Add two integers',
+  request=Specification(schema=request_schema),
+  response=Specification(schema=response_schema),
+):
+  def run(
+    self,
+    a: int,
+    b: int,
+  ):
+    return a + b
+```
+
+위 Run은 AsyncAPI `operations`와 Metrics에서 모두 `add`라는 키를 사용한다.
+`name`을 생략하면 Run 모듈명과 클래스의 `__qualname__`을 결합한 이름을 사용한다.
+`description`은 AsyncAPI Operation에만 나타나며 request·response 메시지 설명에는
+적용하지 않는다.
+
+## 4. 호환성 영향
+
+- `Specification(description=...)`는 더 이상 지원하지 않는다. 작업 설명은 Run
+  클래스 정의의 `description`으로 옮겨야 한다.
+- AsyncAPI Operation 이름을 지정하지 않으면 기존 클래스명 단독 키 대신
+  `모듈명.__qualname__`이 사용된다. 이 키를 참조하는 클라이언트는 갱신해야 한다.
+- Metrics 작업 키는 기본값에서 기존 `모듈명.__qualname__` 형식을 유지한다.
+- 동일한 유효 이름의 Run은 Worker 등록에서 거부한다. Metrics 및 AsyncAPI 문서
+  생성 경계에서도 덮어쓰기를 방지하도록 중복을 검사한다.
+
+## 5. 검증 결과
+
+### 자동 테스트 및 정적 진단
+
+- 최초 Python 3.12 검증의 `unittest discover -s test`: **199개 실행 중
+  191개 통과, 8개 건너뜀**. 이 결과는 Python 3.9·3.10 호환성 검증을 포함하지 않았다.
+- Run 이름·설명, 입력 검증, 기본 이름, 상속 비적용, 등록·문서 충돌,
+  AsyncAPI 설명과 Metrics 키의 회귀 테스트를 추가했다.
+- 변경한 `Run.py`, `Specification.py`, `Metrics.py`, `Specifications.py`에
+  Pylance 진단 오류가 없다.
+- `Run.__init_subclass__`의 기존 호출 지점과 새 시그니처가 호환됨을 확인했다.
+- RabbitMQ와 Redis 샘플 파일의 `py_compile` 검사를 통과했다.
+
+### Docker 브로커 실행
+
+로컬 Docker에 임시 RabbitMQ `3.13-management`와 Redis `7.4-alpine`을 실행하고
+각 Worker 샘플을 실제 브로커에 연결했다. Redis는 샘플 기본 연결 설정을 사용했고,
+RabbitMQ는 로컬 guest 계정을 사용했다.
+
+| 샘플 | AsyncAPI·Health | Metrics 처리 결과 | 브로커 상태 |
+|---|---|---|---|
+| RabbitMQ | `/status` 200, Operation 키 `add`, `divide` 및 설명 확인 | 격리 확인에서 각 작업 5건 성공, active 0 | 두 큐의 ready·unacknowledged 모두 0 |
+| Redis | `/status` 200, Operation 키 `add`, `divide` 및 설명 확인 | Add 5건 성공, Divide 4건 성공·1건 실패, active 0 | 각 스트림에 샘플 메시지 5건 기록 |
+
+Redis의 Divide 실패는 샘플이 의도적으로 넣는 0 나눗셈 입력에서 발생했다.
+각 샘플이 모두 Inspector 기본 포트 `9999`를 사용하므로 HTTP 응답은 워커를
+하나씩 분리하여 확인했다. 검증 후 Worker 프로세스와 임시 컨테이너를 종료하고
+샘플 프로세스 및 포트 리스너가 남지 않았음을 확인했다.
+
+전체 테스트 중 8개는 선택적 통합 테스트로 건너뛰었다. 이번 로컬 Docker 실행은
+브로커와 샘플의 실제 연동 검증이며, 전체 브로커 어댑터 테스트 스위트 실행으로
+간주하지 않는다.
+
+## 6. Python 3.9·3.10 호환성 수정
+
+Python 3.9.13과 3.10.11에서 클래스 정의의 `name=` 키워드가
+`ABCMeta.__new__(mcls, name, bases, namespace, **kwargs)`의 클래스 이름 인자와
+충돌하는 것을 재현했다. 이 경우 `Run.__init_subclass__`에 도달하기 전에
+`TypeError: __new__() got multiple values for argument 'name'`이 발생한다.
+
+`ABCMeta`를 상속한 `RunMeta`를 추가하여 공개 `name=`을 내부 `run_name` 키워드로
+변환한 뒤 기존 추상 클래스 생성 경로로 전달한다. 이름의 기본값·검증·상속 비적용
+처리는 계속 `Run.__init_subclass__`가 담당한다. 사용자 클래스 정의 문법은
+변경하지 않으며 `ABCMeta`의 추상 메서드 검사도 유지한다.
+
+[Worker 테스트](../../../test/test_worker.py)에 이름을 지정한 추상 Run의 생성 거부,
+구체 하위 Run의 이름 재정의 및 실행을 검증하는 회귀 테스트를 추가했다.
+
+| Python | 전체 코어 테스트 결과 |
+|---|---|
+| 3.9.13 | 200개 실행, 192개 통과, 8개 건너뜀 |
+| 3.10.11 | 200개 실행, 192개 통과, 8개 건너뜀 |
+| 3.12.10 | 200개 실행, 192개 통과, 8개 건너뜀 |
+| 3.14.5 | 200개 실행, 192개 통과, 8개 건너뜀 |
+
+구버전 테스트는 개발 환경의 Redis 8.x 클라이언트가 해당 버전과 호환되지 않아
+세션 전용 경로에 Redis 5.3.1과 의존성을 설치하여 실행했다. 프로젝트의
+의존성 선언과 공용 가상환경은 변경하지 않았다.
+Python 3.9의 첫 전체 실행에서는 무관한 Console HTTP 테스트에 Windows
+`ConnectionAbortedError`가 발생했으나, 해당 테스트의 단독 실행과 전체 재실행은
+통과했다. 변경한 Run 소스의 Pylance 진단에도 오류가 없다.
+
+## 7. 명시적 이름의 허용 문자 변경
+
+Python 식별자 제한을 제거하고 영문 대소문자·숫자·`_`·`.`·`-`를 하나 이상
+허용하도록 변경했다. 위치 제한은 없으며 Python 예약어도 허용한다.
+빈 문자열, 공백·개행, 한국어 등 다른 문자는 거부한다.
+대소문자 변환이나 공백 제거 없이 지정한 이름을 그대로 사용한다.
+미지정 이름의 `모듈명.__qualname__` 생성 규칙과 중복 검사는 유지한다.
+
+허용·거부 문자 조합과 입력값 보존, AsyncAPI Operation 키 및 Metrics
+스냅샷·Prometheus 레이블의 동일 이름 사용을 회귀 테스트로 검증한다.
+
+- Python 3.12.10: 전체 201개 실행, 193개 통과, 선택적 테스트 8개 건너뜀.
+- Python 3.9.13·3.10.11: 각 관련 테스트 43개 실행, 40개 통과, 3개 건너뜀.
+- 변경한 Run 소스의 Pylance 진단 및 변경 파일 공백 검사 통과.

defstream-0.1.11/issues/fix/10/README.md

@@ -0,0 +1,44 @@
+# Run 에 이름(name)과 설명(description) 지원
+
+## 변경 요약
+
+Run 정의에서 `name`과 `description`을 지정할 수 있습니다. 지정한 이름은 AsyncAPI
+`operations`와 Metrics의 작업 키에서 함께 사용됩니다. `name`을 생략하면
+`모듈명.__qualname__`이 기본 이름입니다.
+
+## 사용 방법
+
+```python
+from DefStream.Worker import Run, Specification
+
+
+class Add(
+  Run,
+  name='add',
+  description='Add two integers',
+  request=Specification(schema=request_schema),
+  response=Specification(schema=response_schema),
+):
+  def run(
+    self,
+    a: int,
+    b: int,
+  ):
+    return a + b
+```
+
+Run 등록 후 AsyncAPI Operation 키와 Metrics 작업 식별자는 `add`입니다.
+명시적 이름은 영문 대소문자·숫자·`_`·`.`·`-`로만 구성된 한 글자 이상의 문자열입니다
+(`Orders.create-v2_Job` 등). 위치 제한은 없고 Python 예약어도 허용합니다.
+공백·한국어·그 외 문자는 허용하지 않으며, 입력을 변환하지 않고 대소문자를
+구분합니다. Worker에 같은 이름을 가진 Run을 함께 등록할 수 없습니다.
+
+## 기존 코드에 미치는 영향
+
+- `Specification(description=...)`는 제거되었습니다. 설명을 Run의
+  `description`으로 옮기세요. 설명은 AsyncAPI Operation에 반영되며 메시지 설명에는
+  적용하지 않습니다.
+- AsyncAPI Operation의 기본 키는 클래스명에서 `모듈명.__qualname__`으로
+  변경됩니다. Operation 키를 사용하는 클라이언트 설정도 갱신하세요.
+- Metrics의 기본 작업 키는 기존 qualified 클래스 이름 형식과 같습니다.
+- Run 하위 클래스는 상위 Run의 `name`이나 `description`을 상속하지 않습니다.

defstream-0.1.11/issues/fix/10/REQUIREMENTS.md

@@ -0,0 +1,88 @@
+# Run 에 이름(name)과 설명(description) 지원
+
+## 1. 목적
+
+Run을 정의할 때 이름과 설명을 선택적으로 지정할 수 있도록 한다. 지정한
+이름을 AsyncAPI `operations`의 키와 Metrics의 작업 키로 공통 사용하며,
+이름을 지정하지 않으면 `모듈.클래스명`을 사용한다. 설명은 AsyncAPI Operation에
+반영한다. `Specification`에서는 `description`을 제거한다.
+
+본 문서는 구현 전 요구사항 명세이다.
+
+## 2. 범위
+
+### 포함
+
+- Run 정의 시 선택적 `name` 및 `description` 지정.
+- Run별 유효 이름 결정 및 AsyncAPI와 Metrics에서의 일관된 사용.
+- 이름의 입력 검증, 충돌 처리, 기본 이름과 기존 동작의 호환성 검증.
+- `Specification`에서 `description` 제거 및 설명의 Run 단위 관리.
+
+### 제외
+
+- AsyncAPI 채널 주소, 메시지 키·이름 또는 payload 변경.
+- Metrics 집계 방식, 지표 이름, 기간 및 응답 형식 변경.
+- Run의 실행·검증·메시지 처리 방식 변경.
+
+## 3. 용어 및 현재 동작
+
+| 용어 | 의미 |
+|---|---|
+| Run 이름 | Run 정의에 선택적으로 지정하는 사용자 제공 식별자 |
+| 유효 Run 이름 | AsyncAPI와 Metrics에서 해당 Run을 식별하는 공통 문자열 |
+| 기본 이름 | 명시적 이름이 없을 때 사용하는 `Run.__module__ + '.' + Run.__qualname__` |
+| Run 설명 | Run 정의에 선택적으로 지정하여 AsyncAPI Operation에 반영하는 문자열 |
+
+- AsyncAPI `operations`의 현재 키는 Run 클래스의 `__name__`이다.
+- Metrics의 현재 작업 키는 Run 클래스의 `__module__`과 `__qualname__`을
+  결합한 값이다.
+- 변경 후에는 AsyncAPI와 Metrics가 모두 동일한 유효 Run 이름을 사용한다.
+- 현재 `Specification`은 `description`을 받아 메시지 및 Operation 설명에
+  활용한다. 변경 후 설명은 Run 정의에서 관리하고 Specification에는 두지 않는다.
+
+## 4. 기능 요구사항
+
+| ID | 요구사항 |
+|---|---|
+| SPECNAME-01 | Run 정의 시 선택적 `name`을 지정할 수 있어야 한다. 지정하지 않은 경우의 기본값은 미지정 상태여야 한다. |
+| SPECNAME-02 | Run 정의 시 선택적 `description`을 지정할 수 있어야 한다. 지정하지 않은 경우 설명은 없어야 한다. |
+| SPECNAME-03 | 명시적 `name`은 `[A-Za-z0-9_.-]+` 전체 일치 문자열이어야 한다. 영문 대소문자·숫자·`_`·`.`·`-`를 위치 제한 없이 허용하고 Python 예약어도 허용한다. 빈 문자열, 공백, 한국어 및 그 외 문자는 `ValueError`, 문자열과 `None` 이외의 타입은 `TypeError`로 거부한다. 입력을 정규화하지 않고 대소문자를 구분하여 보존한다. |
+| SPECNAME-04 | `description`은 문자열 또는 `None`이어야 한다. 다른 타입은 `TypeError`로 명확히 거부한다. 빈 설명 문자열은 그대로 보존한다. |
+| SPECNAME-05 | 이름이 지정되지 않은 Run의 유효 이름은 `Run.__module__ + '.' + Run.__qualname__`이어야 한다. 중첩 클래스도 `__qualname__`을 포함해야 한다. |
+| SPECNAME-06 | AsyncAPI 문서의 `operations` 객체에서 각 Run의 키로 유효 Run 이름을 사용해야 한다. 이 요구사항은 Operation 객체의 별도 필드가 아니라 `operations` 맵의 키에 적용한다. |
+| SPECNAME-07 | Run의 `description`이 지정된 경우 AsyncAPI Operation의 `description`으로 사용해야 한다. 지정하지 않은 경우 해당 필드는 생성하지 않는다. |
+| SPECNAME-08 | `Specification` 생성자는 `description` 인자를 더 이상 받지 않아야 한다. 기존 description positional 인자에 의존하는 호출은 Run의 `description`으로 이전해야 하며, 제거된 인자를 전달하면 기존 Python 호출 규칙에 따라 명확히 실패해야 한다. |
+| SPECNAME-09 | Metrics의 작업 저장 키와 해당 작업을 식별하는 출력 키·레이블은 유효 Run 이름을 사용해야 한다. Metrics 집계 내용과 지표 구조는 변경하지 않는다. |
+| SPECNAME-10 | 서로 다른 Run이 같은 유효 이름을 가지면 Run 등록 시와 AsyncAPI 문서 생성 시 충돌을 감지해야 한다. 데이터가 조용히 덮어써지거나 합쳐지지 않도록 원인을 알 수 있는 예외로 거부한다. |
+| SPECNAME-11 | Run에 이름을 지정하지 않은 경우 AsyncAPI와 Metrics 모두 같은 `모듈.클래스명` 기본 이름을 사용해야 한다. 이는 기존 AsyncAPI의 클래스명 단독 키를 qualified 이름으로 바꾸는 의도된 호환성 변경이다. |
+| SPECNAME-12 | Run의 `name`과 `description`은 해당 Run 정의에 적용하며, 하위 Run 정의가 값을 지정하지 않으면 상위 Run의 메타데이터를 상속하지 않는다. 이름 미지정 하위 Run은 자체 모듈·클래스명으로 식별되고 설명도 미지정 상태가 된다. |
+
+## 5. 동작 보장 및 호환성
+
+- 사용자 지정 이름은 AsyncAPI와 Metrics에서 동일한 문자열로 사용한다.
+- 이름은 AsyncAPI Operation의 키와 Metrics 작업 식별자에만 적용한다.
+  채널 주소, request/response 메시지 이름과 payload 구성은 기존 규칙을 유지한다.
+- 설명은 AsyncAPI Operation에만 적용한다. request/response 메시지 설명은
+  Specification에서 제거되며, 이번 변경에서 별도 대체 메타데이터를 추가하지 않는다.
+- 이름이 없는 Run의 Metrics 키 형식은 기존과 같다. AsyncAPI 키는 기존의
+  클래스명 단독 형식에서 `모듈.클래스명` 형식으로 변경된다.
+- 이름 및 설명 지정 여부와 관계없이 Specification의 schema, validator,
+  example, format 검증 및 payload 문서화 동작을 유지한다. 단,
+  Specification의 `description`은 의도적으로 제거한다.
+- 중복 이름을 허용하지 않는 기존 AsyncAPI 동작을 보존하고, Metrics에서도
+  이름 중복으로 작업 데이터가 유실되지 않도록 한다.
+
+## 6. 인수 기준
+
+| ID | 검증 시나리오 및 기대 결과 |
+|---|---|
+| WAT-01 | `Run` 정의에 `name='orders'`를 지정하면 AsyncAPI `operations`와 Metrics에서 `orders` 키로 식별된다. |
+| WAT-02 | 이름을 지정하지 않은 모듈 최상위 Run의 AsyncAPI 키와 Metrics 키가 모두 `모듈명.클래스명`이다. |
+| WAT-03 | 이름을 지정하지 않은 중첩 Run의 기본 이름에 모듈명과 중첩 경로를 포함한 `__qualname__`이 반영된다. |
+| WAT-04 | `Orders.create-v2_Job`, 숫자만 있는 이름, Python 예약어 및 구분자로 시작·끝나는 이름을 그대로 허용한다. 빈 문자열, 한국어, 공백·개행 및 허용 범위 밖 문자는 `ValueError`, 문자열과 `None` 이외의 타입은 `TypeError`로 거부한다. |
+| WAT-05 | `description`이 문자열이면 AsyncAPI Operation 설명에 반영되고, `None`이면 Operation에 설명 필드가 없다. |
+| WAT-06 | `description`에 문자열 또는 `None` 이외의 값을 전달하면 `TypeError`가 발생한다. |
+| WAT-07 | 두 Run에 같은 사용자 지정 이름을 지정하면 Run 등록 시 충돌을 감지하고, 문서 생성에서도 충돌을 검증한다. 기존 항목을 덮어쓰거나 통계를 합치지 않는다. |
+| WAT-08 | Run의 하위 클래스가 이름과 설명을 재지정하지 않으면 상위 값이 상속되지 않는다. 하위 Run은 자신의 기본 이름을 사용하고 설명은 미지정으로 남는다. |
+| WAT-09 | `Specification(description=...)` 호출은 지원되지 않으며, 이를 사용하는 기존 코드는 Run의 설명 지정 방식으로 이전해야 한다. |
+| WAT-10 | 채널 주소, request/response 메시지 키, payload, Metrics 집계값이 이름 지정 전후 기존 계약을 유지한다. |

{defstream-0.1.9 → defstream-0.1.11}/sample/Worker/RabbitMQ/Tasks.py

@@ -65,8 +65,9 @@ class Add(
 		'queue': 'add',
 	},
 	on_error=Requeue(),
+	name='add',
+	description='Add two integers',
 	request=Specification(
-		description='Addition request',
 		schema=Object(
 			properties=Properties(
 				a=Integer('First operand'),
@@ -89,7 +90,6 @@ class Add(
 		},
 	),
 	response=Specification(
-		description='Addition response',
 		schema=Integer('Sum'),
 		validator=Validator(IsInteger()),
 		example=30,
@@ -115,8 +115,9 @@ class Divide(
 		queue='divide',
 	),
 	on_error=Reject(),
+	name='divide',
+	description='Divide a dividend by a divisor',
 	request=Specification(
-		description='Division request',
 		schema=Object(
 			properties=Properties(
 				a=Integer('Dividend'),
@@ -139,7 +140,6 @@ class Divide(
 		},
 	),
 	response=Specification(
-		description='Division response',
 		schema=Number('Quotient'),
 		validator=Validator(IsNumber()),
 		example=5.0,

{defstream-0.1.9 → defstream-0.1.11}/sample/Worker/Redis/Sample.py

@@ -56,6 +56,8 @@ def configure_logging() -> None:
 class Add(
 	Run,
 	parameters=Subscription('add'),
+	name='add',
+	description='Add two integers',
 ):
 	def run(
 		self,
@@ -76,6 +78,8 @@ class Divide(
 	Run,
 	parameters=Subscription('divide'),
 	on_error=Reject(),
+	name='divide',
+	description='Divide a dividend by a divisor',
 ):
 	def run(
 		self,

{defstream-0.1.9 → defstream-0.1.11}/src/Inspector/Extensions/Metrics.py

@@ -122,13 +122,15 @@ class Metrics(Extension):
 		worker = inspector.worker
 		if worker is None:
 			raise RuntimeError('Metrics requires an attached Worker')
+		tasks = {}
+		for task in worker.tasks:
+			if task.name in tasks:
+				raise ValueError('Duplicate Metrics task name: ' + task.name)
+			tasks[task.name] = TaskMetrics()
 		with self.lock:
 			self.started_at = monotonic()
 			self.instance = uuid4().hex
-			self.tasks = {
-				task.__module__ + '.' + task.__qualname__: TaskMetrics()
-				for task in worker.tasks
-			}
+			self.tasks = tasks
 		self.logger.info(
 			'Metrics collection initialized: path=%s tasks=%d',
 			self.path,

{defstream-0.1.9 → defstream-0.1.11}/src/Inspector/Extensions/Specifications.py

@@ -3,6 +3,7 @@ from json import dumps
 from logging import getLogger
 from re import fullmatch
 from typing import (
+	Any,
 	TYPE_CHECKING,
 	Optional,
 )
@@ -72,10 +73,10 @@ class Specifications(Extension):
 		}
 		if self.description is not None:
 			info['description'] = self.description
-		channels = {}
-		operations = {}
+		channels: dict[str, Any] = {}
+		operations: dict[str, Any] = {}
 		for task in worker.tasks:
-			key = task.__name__
+			key = task.name
 			if key in operations:
 				raise ValueError('Duplicate task specification identifier: ' + key)
 			parameters = task.parameters
@@ -102,7 +103,7 @@ class Specifications(Extension):
 				raise ValueError('Task specification requires a nonempty queue address: ' + key)
 			if queue in channels:
 				raise ValueError('Duplicate channel identifier: ' + queue)
-			message = task.request.document() if task.request is not None else {
+			message: dict[str, Any] = task.request.document() if task.request is not None else {
 				'payload': {'type': 'object'},
 			}
 			message['name'] = task.__name__ + 'Request'
@@ -123,8 +124,8 @@ class Specifications(Extension):
 					'request',
 				)],
 			}
-			if task.request is not None and task.request.description is not None:
-				operation['description'] = task.request.description
+			if task.description is not None:
+				operation['description'] = task.description
 			if task.response is not None:
 				channels[queue]['messages']['response'] = task.response.document()
 				operation['reply'] = {

{defstream-0.1.9 → defstream-0.1.11}/src/Worker/Run.py

@@ -1,12 +1,15 @@
 from abc import (
 	ABC,
+	ABCMeta,
 	abstractmethod,
 )
 from collections.abc import Mapping
 from logging import getLogger
+from re import fullmatch
 from time import monotonic
 from typing import (
 	Any,
+	Dict,
 	Optional,
 	Sequence,
 	Tuple,
@@ -81,9 +84,33 @@ class RunError(ABC):
 		raise NotImplementedError
 
 
-class Run(ABC):
+class RunMeta(ABCMeta):
+	"""구버전 ABCMeta의 클래스 이름 인자와 Run의 name 키워드 충돌을 방지한다."""
+
+	def __new__(
+		mcls,
+		class_name: str,
+		bases: Tuple[type, ...],
+		namespace: Dict[str, Any],
+		/,
+		**kwargs: Any,
+	) -> 'RunMeta':
+		if 'name' in kwargs:
+			kwargs['run_name'] = kwargs.pop('name')
+		return super().__new__(
+			mcls,
+			class_name,
+			bases,
+			namespace,
+			**kwargs,
+		)
+
+
+class Run(ABC, metaclass=RunMeta):
 	logger = getLogger('DefStream.Run')
 	parameters: Any = None
+	name: str = __module__ + '.' + __qualname__
+	description: Optional[str] = None
 	on_error: Optional[EventError] = None
 	setups: Tuple[RunSetup, ...] = ()
 	completes: Tuple[RunComplete, ...] = ()
@@ -94,6 +121,8 @@ class Run(ABC):
 	def __init_subclass__(
 		cls,
 		*,
+		run_name: Optional[str] = None,
+		description: Optional[str] = None,
 		parameters: Any = None,
 		on_error: Optional[EventError] = None,
 		setups: Optional[Union[RunSetup, Sequence[RunSetup]]] = None,
@@ -104,6 +133,23 @@ class Run(ABC):
 		**kwargs,
 	):
 		super().__init_subclass__(**kwargs)
+		if run_name is not None and not isinstance(
+			run_name,
+			str,
+		):
+			raise TypeError('Run name must be a string or None')
+		if run_name is not None and fullmatch(
+			r'[A-Za-z0-9_.-]+',
+			run_name,
+		) is None:
+			raise ValueError('Run name must contain only ASCII letters, digits, underscores, dots or hyphens')
+		if description is not None and not isinstance(
+			description,
+			str,
+		):
+			raise TypeError('Run description must be a string or None')
+		cls.name = run_name if run_name is not None else cls.__module__ + '.' + cls.__qualname__
+		cls.description = description
 		parents = tuple(base for base in cls.__mro__[1:] if issubclass(
 			base,
 			Run,

{defstream-0.1.9 → defstream-0.1.11}/src/Worker/Specification.py

@@ -29,7 +29,6 @@ class Specification:
 		schema: Any = None,
 		validator: Optional[Callable[[Any], Any]] = None,
 		example: Any = ...,
-		description: Optional[str] = None,
 		format: str = 'application/json',
 	):
 		if not isinstance(
@@ -60,7 +59,6 @@ class Specification:
 		self.schema = schema
 		self.validator = validator
 		self.example = example
-		self.description = description
 		self.format = format
 		self.document()
 
@@ -84,8 +82,6 @@ class Specification:
 			'contentType': self.format,
 			'payload': payload,
 		}
-		if self.description is not None:
-			message['description'] = self.description
 		if self.example is not ...:
 			message['examples'] = [{'payload': deepcopy(self.example)}]
 		return message

{defstream-0.1.9 → defstream-0.1.11}/src/Worker/Worker.py

@@ -102,6 +102,11 @@ class Worker:
 		task_parameters(run)
 		if run in self.tasks:
 			raise ValueError('Run is already registered')
+		if any(
+			registered.name == run.name
+			for registered in self.tasks
+		):
+			raise ValueError('Duplicate Run name: ' + run.name)
 		self.tasks.append(run)
 		self.logger.debug(
 			'Task registered: task=%s.%s',
@@ -246,7 +251,7 @@ class Worker:
 			self.pending -= 1
 			raise RuntimeError('Worker consumer is not initialized')
 		inspector = self.inspector
-		task = run.__module__ + '.' + run.__qualname__
+		task = run.name
 		self.logger.debug(
 			'Task message received: task=%s pending=%s',
 			task,