DefStream-RabbitMQ 0.1.1__tar.gz → 0.1.1.3__tar.gz

defstream_rabbitmq-0.1.1.3/.github/workflows/ci.yml

@@ -0,0 +1,403 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+env:
+  RELEASE_SERIES: '0.1'
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  changes:
+    name: Plan release version
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      release: ${{ steps.changes.outputs.release }}
+      version: ${{ steps.changes.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up release planner Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.13'
+      - name: Check complete push range and plan version
+        id: changes
+        env:
+          BEFORE: ${{ github.event.before }}
+          RELEASE_PUSH: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        run: |
+          python - <<'PY'
+          from os import environ
+          from pathlib import Path
+          from re import fullmatch
+          from subprocess import check_output
+
+          if environ['RELEASE_PUSH'] != 'true':
+              with Path(environ['GITHUB_OUTPUT']).open('a', encoding='utf-8') as output:
+                  output.write('release=false\n')
+              raise SystemExit(0)
+          series = environ['RELEASE_SERIES']
+          if fullmatch(r'(0|[1-9]\d*)\.(0|[1-9]\d*)', series) is None:
+              raise ValueError(f'Invalid RELEASE_SERIES: {series!r}')
+          before = environ['BEFORE']
+          if not before:
+              raise ValueError('Missing push base commit')
+          first_push = set(before) == {'0'}
+          base = check_output(['git', 'hash-object', '-t', 'tree', '--stdin'], input='', text=True).strip() if first_push else before
+          changed = check_output(
+              ['git', 'diff', '--name-only', '--no-renames', base, environ['GITHUB_SHA'], '--', 'src/'],
+              text=True,
+          ).strip()
+          # Anchor to the pre-push history so a rerun ignores its own release tag.
+          tags = [] if first_push else check_output(['git', 'tag', '--merged', before], text=True).splitlines()
+          releases = []
+          for tag in tags:
+              match = fullmatch(r'v?(\d+)\.(\d+)\.(\d+)(?:\.(\d+))?(?:\.post\d+)?', tag)
+              if match and f'{int(match[1])}.{int(match[2])}' == series:
+                  releases.append(tuple(map(int, match.groups()[:3])) + (int(match[4] or 0),))
+          latest = max(releases) if releases else None
+          number = int(environ['GITHUB_RUN_NUMBER'])
+          if number < 1:
+              raise ValueError('Build number must be positive')
+          if latest is not None and number <= latest[3]:
+              raise ValueError('Build number must exceed the previous build; do not reset the workflow counter')
+          if changed:
+              patch = latest[2] + 1 if latest is not None else 0
+              print(f'Source changes:\n{changed}')
+          else:
+              if latest is None:
+                  raise ValueError(
+                      'No release tag in pre-push history for this series. '
+                      'Tag the exact source commit of the existing PyPI release before retrying.'
+                  )
+              patch = latest[2]
+              print('No src changes: keeping MAJOR.MINOR.PATCH and increasing BUILD')
+          version = f'{series}.{patch}.{number}'
+          print(f'Planned version: {version}')
+          with Path(environ['GITHUB_OUTPUT']).open('a', encoding='utf-8') as output:
+              output.write(f'release=true\nversion={version}\n')
+          PY
+
+  test:
+    name: Test Python ${{ matrix.python }}
+    needs: changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+    env:
+      PROJECT: ${{ github.event.repository.name }}
+      DEFSTREAM_RABBITMQ_TESTS: '1'
+      DEFSTREAM_REDIS_TESTS: '1'
+    services:
+      rabbitmq:
+        image: rabbitmq:4.1
+        ports:
+          - 5672:5672
+        env:
+          RABBITMQ_DEFAULT_USER: guest
+          RABBITMQ_DEFAULT_PASS: guest
+          RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS: '-rabbit loopback_users []'
+        options: >-
+          --health-cmd "rabbitmq-diagnostics -q ping"
+          --health-interval 10s
+          --health-timeout 10s
+          --health-retries 12
+      redis:
+        image: redis:7.4
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+    steps:
+      - name: Check out core
+        uses: actions/checkout@v7
+        with:
+          repository: yong5eon/DefStream
+          ref: ${{ github.event.repository.name == 'DefStream' && github.sha || 'master' }}
+          path: packages/DefStream
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Check out RabbitMQ adapter
+        uses: actions/checkout@v7
+        with:
+          repository: yong5eon/DefStream-RabbitMQ
+          ref: ${{ github.event.repository.name == 'DefStream-RabbitMQ' && github.sha || 'master' }}
+          path: packages/DefStream-RabbitMQ
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Check out Redis adapter
+        uses: actions/checkout@v7
+        with:
+          repository: yong5eon/DefStream-Redis
+          ref: ${{ github.event.repository.name == 'DefStream-Redis' && github.sha || 'master' }}
+          path: packages/DefStream-Redis
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Record source commits and tag candidate locally
+        env:
+          RELEASE_BUILD: ${{ needs.changes.outputs.release }}
+          RELEASE_VERSION: ${{ needs.changes.outputs.version }}
+        run: |
+          for package in packages/*; do
+            echo "$package: $(git -C "$package" rev-parse HEAD)"
+          done
+          echo "SOURCE_DATE_EPOCH=$(git -C "packages/$PROJECT" show -s --format=%ct HEAD)" >> "$GITHUB_ENV"
+          python - <<'PY'
+          from os import environ
+          from pathlib import Path
+          from re import fullmatch
+          from subprocess import check_output, run
+
+          project = environ['PROJECT']
+          if project not in ('DefStream', 'DefStream-RabbitMQ', 'DefStream-Redis'):
+              raise ValueError(f'Unexpected project: {project}')
+          if environ['RELEASE_BUILD'] != 'true':
+              print('Test-only build: using the existing Git-derived development version.')
+              raise SystemExit(0)
+          version = environ['RELEASE_VERSION']
+          if fullmatch(r'(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\.[1-9]\d*', version) is None:
+              raise ValueError(f'Invalid planned version: {version!r}')
+          path = Path('packages') / project
+          tag = version
+          tags = check_output(['git', '-C', str(path), 'tag', '--list', tag], text=True).strip()
+          if tags:
+              tagged = check_output(['git', '-C', str(path), 'rev-parse', f'{tag}^{{commit}}'], text=True).strip()
+              if tagged != environ['GITHUB_SHA']:
+                  raise RuntimeError(f'{tag} already points at another commit')
+          else:
+              run(['git', '-C', str(path), 'tag', tag, environ['GITHUB_SHA']], check=True)
+          print(f'{project}: local candidate {tag}')
+          with Path(environ['GITHUB_STEP_SUMMARY']).open('a', encoding='utf-8') as summary:
+              summary.write(f'## {project} {version}\n\nSource: `{environ["GITHUB_SHA"]}`\n')
+          PY
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Build source distributions and wheels
+        run: |
+          mkdir -p dist dependency-wheels
+          for name in DefStream DefStream-RabbitMQ DefStream-Redis; do
+            if [ "$name" = "$PROJECT" ]; then
+              python -m build --outdir "$GITHUB_WORKSPACE/dist" "packages/$name"
+            else
+              python -m build --outdir "$GITHUB_WORKSPACE/dependency-wheels" "packages/$name"
+            fi
+          done
+          python -m twine check --strict dist/*
+
+      - name: Install built wheels into a clean environment
+        run: |
+          python -m venv "$RUNNER_TEMP/installed"
+          "$RUNNER_TEMP/installed/bin/python" -m pip install dist/*.whl dependency-wheels/*.whl
+          "$RUNNER_TEMP/installed/bin/python" -m pip check
+
+      - name: Test installed package
+        run: |
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/installed/bin/python" -m unittest discover \
+            -s "$GITHUB_WORKSPACE/packages/$PROJECT/test" -p 'test_*.py' -v
+
+      - name: Set up Node for core UI tests
+        if: env.PROJECT == 'DefStream'
+        uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+
+      - name: Test core UI
+        if: env.PROJECT == 'DefStream'
+        run: node --test packages/DefStream/test/test_dashboard_ui.cjs
+
+      - name: Preserve verified release distributions
+        if: needs.changes.outputs.release == 'true' && matrix.python == '3.13'
+        uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    name: Publish PyPI
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master' && needs.changes.outputs.release == 'true'
+    needs: [changes, test]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      contents: write
+    steps:
+      - name: Check out release source for tagging
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.sha }}
+          path: release-source
+          fetch-depth: 0
+
+      - name: Download verified distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: distributions
+          path: dist
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.13'
+
+      - name: Check release status
+        id: release
+        env:
+          PROJECT: ${{ github.event.repository.name }}
+          RELEASE_VERSION: ${{ needs.changes.outputs.version }}
+        run: |
+          python - <<'PY'
+          from email.parser import BytesParser
+          from json import load
+          from os import environ
+          from pathlib import Path
+          from urllib.error import HTTPError
+          from urllib.request import urlopen
+          from zipfile import ZipFile
+
+          wheels = list(Path('dist').glob('*.whl'))
+          sources = list(Path('dist').glob('*.tar.gz'))
+          if len(wheels) != 1 or len(sources) != 1:
+              raise ValueError('Expected exactly one wheel and one source distribution')
+          with ZipFile(wheels[0]) as archive:
+              metadata_path, = (name for name in archive.namelist() if name.endswith('.dist-info/METADATA'))
+              metadata = BytesParser().parsebytes(archive.read(metadata_path))
+          project = environ['PROJECT']
+          if metadata['Name'] != project:
+              raise ValueError(f'Unexpected distribution: {metadata["Name"]}')
+          version = metadata['Version']
+          expected_version = environ['RELEASE_VERSION']
+          if version != expected_version:
+              raise ValueError(f'Expected {expected_version}, got {version}')
+          try:
+              with urlopen(f'https://pypi.org/pypi/{project}/{version}/json', timeout=30) as response:
+                  release = load(response)
+          except HTTPError as error:
+              if error.code != 404:
+                  raise
+              exists = False
+          else:
+              expected = {wheels[0].name, sources[0].name}
+              published = {file['filename'] for file in release['urls']}
+              if int(environ['GITHUB_RUN_ATTEMPT']) == 1 or not expected.issubset(published):
+                  raise RuntimeError(
+                      f'{project} {version} already exists or is partially published. '
+                      'Do not overwrite it; use a new run/version or repair the release manually.'
+                  )
+              print(f'{project} {version}: already published; skipping this rerun')
+              exists = True
+          with Path(environ['GITHUB_OUTPUT']).open('a', encoding='utf-8') as output:
+              output.write(f'publish={str(not exists).lower()}\n')
+              output.write(f'version={version}\n')
+          PY
+
+      - name: Record verified release tag
+        env:
+          VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          tag="$VERSION"
+          cd release-source
+          if git show-ref --verify --quiet "refs/tags/$tag"; then
+            if [ "$(git rev-parse "$tag^{commit}")" != "$GITHUB_SHA" ]; then
+              echo "::error::$tag already points at another commit."
+              exit 1
+            fi
+          else
+            git tag "$tag" "$GITHUB_SHA"
+          fi
+          git push origin "refs/tags/$tag"
+
+      - name: Install upload tool
+        if: steps.release.outputs.publish == 'true'
+        run: python -m pip install --upgrade twine
+
+      - name: Upload to PyPI
+        if: steps.release.outputs.publish == 'true'
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          if [ -z "$TWINE_PASSWORD" ]; then
+            echo "::error::Configure PYPI_API_TOKEN in the pypi environment or repository Actions secrets."
+            exit 1
+          fi
+          python -m twine upload --non-interactive dist/*
+
+      - name: Publish GitHub Release with verified distributions
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          python - <<'PY'
+          from json import load
+          from os import environ
+          from pathlib import Path
+          from subprocess import run
+          from urllib.error import HTTPError
+          from urllib.parse import quote
+          from urllib.request import Request, urlopen
+
+          repository = environ['GITHUB_REPOSITORY']
+          version = environ['VERSION']
+          request = Request(
+              f'{environ["GITHUB_API_URL"]}/repos/{repository}/releases/tags/{quote(version, safe="")}',
+              headers={
+                  'Authorization': f'Bearer {environ["GH_TOKEN"]}',
+                  'Accept': 'application/vnd.github+json',
+                  'X-GitHub-Api-Version': '2022-11-28',
+              },
+          )
+          try:
+              with urlopen(request, timeout=30) as response:
+                  release = load(response)
+          except HTTPError as error:
+              if error.code != 404:
+                  raise
+              run([
+                  'gh', 'release', 'create', version, '--repo', repository,
+                  '--verify-tag', '--title', version, '--generate-notes', '--draft',
+              ], check=True)
+          else:
+              if release['tag_name'] != version:
+                  raise ValueError('GitHub Release does not match the verified version')
+          artifacts = sorted(str(path) for path in Path('dist').iterdir() if path.is_file())
+          run([
+              'gh', 'release', 'upload', version, '--repo', repository,
+              '--clobber', *artifacts,
+          ], check=True)
+          run([
+              'gh', 'release', 'edit', version, '--repo', repository, '--draft=false',
+          ], check=True)
+          PY

defstream_rabbitmq-0.1.1.3/.gitignore

@@ -0,0 +1,58 @@
+# Python bytecode and caches
+__pycache__/
+*.py[codz]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+.coverage
+.coverage.*
+
+# Virtual environments and local environment files
+.venv/
+venv/
+env/
+.env
+.env.*
+
+# Python packaging and build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+.Python
+
+# Operating system files
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Miscellaneous files
+*.log
+*.tmp
+*.bak
+*.swp
+*.swo
+
+# Temporary files
+tmp/
+*.tmp
+*.temp
+
+# IDE and editor specific files
+.vscode/
+.idea/
+
+# Git
+.git/
+
+# GitHub specific files
+.github/
+!/.github/
+/.github/*
+!/.github/workflows/
+
+# GitLab specific files
+.gitlab/

defstream_rabbitmq-0.1.1.3/DefStream_RabbitMQ.egg-info/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: DefStream-RabbitMQ
+Version: 0.1.1.3
+Summary: RabbitMQ broker adapter for DefStream
+Home-page: https://github.com/yong5eon/DefStream-RabbitMQ
+Author: Heo Yongseon
+Project-URL: Source, https://github.com/yong5eon/DefStream-RabbitMQ
+Project-URL: Issues, https://github.com/yong5eon/DefStream-RabbitMQ/issues
+Project-URL: Releases, https://github.com/yong5eon/DefStream-RabbitMQ/releases
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: DefStream>=0.1.0
+Requires-Dist: pika>=1.3.2
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# DefStream-RabbitMQ
+
+**한국어** | [English](./README.en.md)
+
+DefStream에서 RabbitMQ를 사용할 수 있게 해주는 브로커 어댑터입니다.
+일반 큐, Exchange 라우팅, 스트림 이력 읽기, 동기 RPC를 제공하며,
+DefStream Worker에 연결해 작업을 스레드·프로세스 풀에서 실행할 수 있습니다.
+내부 클라이언트로 Pika를 사용합니다.
+
+## 설치
+
+Python **3.9 이상**과 접속 가능한 RabbitMQ 서버가 필요합니다.
+
+```shell
+python -m pip install DefStream-RabbitMQ
+```
+
+`DefStream>=0.1.0`과 `pika>=1.3.2`도 함께 설치됩니다.
+배포 패키지 이름은 `DefStream-RabbitMQ`이고 import 경로는
+`DefStream.Broker.Implements.RabbitMQ`입니다.
+
+## 큐에 보내고 받기
+
+로컬 RabbitMQ의 `guest` 계정을 사용하는 예제입니다.
+운영에서는 별도 계정과 환경변수·비밀 저장소를 사용하세요.
+예제는 `defstream.example.rabbitmq` 큐를 만들며 실행 후에도 큐를 유지합니다.
+
+```python
+from DefStream.Broker.Implements.RabbitMQ import Configuration, Connection
+
+
+connection = Connection(Configuration(
+  host='127.0.0.1',
+  port=5672,
+  username='guest',
+  password='guest',
+))
+try:
+  connection.connect()
+  connection.create_queue('defstream.example.rabbitmq')
+  queue = connection.queue('defstream.example.rabbitmq')
+  queue.send({'message': 'Hello, DefStream!'})
+  event = queue.pop(timeout=1000)
+  if event is not None:
+    print(event.body)
+    event.ack()
+finally:
+  connection.close()
+```
+
+메시지는 기본 JSON 코덱으로 직렬화됩니다.
+`pop()` 제한 시간은 **밀리초**이며, 양수 제한 시간에 메시지가 없으면 `None`을 반환합니다.
+`None` 또는 `0`은 무기한 대기입니다.
+처리가 성공하면 `ack()`, 재전달하려면 `nack()`, 거부하려면 `reject()`를 호출하세요.
+거부한 메시지는 브로커의 dead-letter 설정이 있으면 해당 목적지로, 없으면 폐기됩니다.
+
+## 연결 설정
+
+| 옵션 | 의미 |
+| --- | --- |
+| `host`, `port` | RabbitMQ 주소와 AMQP 포트 |
+| `username`, `password` | 인증 정보 |
+| `vhost` | 가상 호스트, 기본값 `/` |
+| `ssl` | TLS 사용 여부, 기본값 `False` |
+| `timeout` | blocked-connection 제한 시간, 밀리초 |
+| `heartbeat` | 현재 구현은 `int(heartbeat * 2 / 1000)`초로 변환하여 Pika에 전달 |
+| `encode`, `decode` | 메시지 코덱, 기본값 JSON |
+
+`timeout`은 모든 작업에 대한 전체 실행 제한 시간이 아닙니다.
+일반 연결의 heartbeat는 애플리케이션 작업·유휴 시간에 맞게 설정하고 처리되도록 관리하세요.
+연결과 그 리소스는 **소유 스레드에서만 사용**해야 하며, 스레드·프로세스 사이에 공유하지 마세요.
+
+## Worker로 작업 처리하기
+
+다음은 큐와 오류 큐를 준비한 후 작업을 소비하는 실행 파일입니다.
+
+```python
+from signal import SIGINT, signal
+
+from DefStream.Broker.Implements.RabbitMQ import (
+  Configuration,
+  Connection,
+  Reject,
+  Subscription,
+)
+from DefStream.Worker import Run, ThreadPool, Worker, WorkerSetup, declare
+
+
+class Add(
+  Run,
+  parameters=Subscription(
+    queue='defstream.example.rabbitmq.add',
+    qos=4,
+    error='defstream.example.rabbitmq.add.error',
+  ),
+  on_error=Reject(),
+):
+  def run(
+    self,
+    a: int,
+    b: int,
+  ):
+    return a + b
+
+
+class Prepare(WorkerSetup):
+  def __call__(
+    self,
+    worker: Worker,
+  ) -> None:
+    for task in worker.tasks:
+      declare(
+        task=task,
+        broker=worker.broker,
+      )
+
+
+if __name__ == '__main__':
+  worker = Worker(
+    Connection(Configuration(
+      host='127.0.0.1',
+      port=5672,
+      username='guest',
+      password='guest',
+    )),
+    ThreadPool(4),
+    setups=Prepare(),
+  )
+  worker.add(Add)
+  signal(
+    SIGINT,
+    lambda *_: worker.stop(),
+  )
+  worker.run()
+```
+
+다른 프로세스에서 같은 큐에 `{'a': 10, 'b': 20}`을 보내면 처리됩니다.
+Worker는 실행과 완료 훅이 끝난 뒤 ACK하고, 실패하면 지정한 정책을 적용합니다.
+`on_error`를 생략하면 기본값은 `Requeue()`입니다.
+
+`Subscription` 옵션:
+
+- `queue`: 작업 큐 이름.
+- `qos`: 이 구독의 미확인 메시지 수 제한. 기본 소비자 값은 1이며, 0은 무제한입니다.
+  Worker의 공유 풀 크기와 별개입니다.
+- `error`: `declare()`가 생성하고 연결할 오류 큐 이름. 거부된 메시지의 DLQ입니다.
+- `offset`: RabbitMQ 스트림 구독에 사용할 정수 오프셋.
+
+`Subscription` 객체 생성이나 `consumer.subs()`는 큐를 선언하지 않습니다.
+작업용 `declare()`는 일반 durable 큐와 선택적 DLQ를 준비하며,
+스트림 큐나 Exchange 바인딩을 자동 생성하지 않습니다.
+기존 큐의 선언 옵션이 다르면 실패하며 자동 삭제·재생성하지 않습니다.
+
+## 동기 RPC
+
+실행 중인 Worker가 있는 큐에 `call()`을 사용하면 `Run.run()`의 반환값을 받습니다.
+아래 코드는 앞의 직접 연결 예제에서 `connect()`와 `close()` 사이에 사용하세요.
+
+```python
+result = connection.queue('defstream.example.rabbitmq.add').call(
+  {'a': 10, 'b': 20},
+  timeout=5,
+)
+print(result)
+```
+
+- `timeout`은 **초** 단위이며 응답이 없으면 `TimeoutError`가 발생합니다.
+  이미 전달된 서버 작업을 취소하거나 전체 연결·정리 시간을 엄격히 제한하는 값은 아닙니다.
+- 각 호출은 전용 연결과 임시 응답 큐를 사용하고 종료 시 정리합니다.
+- 서버가 요청을 거부하면 `DefStream.Broker.RemoteError`가 발생합니다.
+  재큐잉은 최종 오류 응답 없이 재시도할 수 있습니다.
+- 응답 발행과 요청 ACK는 원자적이지 않습니다. RPC에서도 중복 실행에 대비하세요.
+
+공유 `Run` 클래스를 사용하는 애플리케이션은 코어의
+`request(body, task=Add, broker=connection, timeout=5)`도 사용할 수 있습니다.
+
+## Exchange와 스트림
+
+- `connection.exchange(name)`은 `send()`와 `call()`을 제공합니다.
+  `event=`가 라우팅 키입니다. Exchange와 큐·바인딩을 먼저 선언하세요.
+- Exchange RPC가 여러 큐로 라우팅되면 여러 곳에서 실행될 수 있으며,
+  클라이언트는 첫 일치 응답만 받습니다. 일반 RPC에는 단일 목적지를 사용하세요.
+- `create_exchange()`, `bind_exchange_to_queue()`, `bind_exchange_to_exchange()`로 라우팅을 구성합니다.
+  각각에 대응하는 `delete_...` 또는 `unbind_...` 메서드도 있습니다.
+- `create_stream()`으로 스트림 큐를 만든 뒤 `connection.stream(name)`의
+  `send()`와 `read(offset=0, timeout=1000)`을 사용합니다. 읽기 제한 시간은 밀리초입니다.
+  읽은 이벤트는 이터레이터가 다음 단계로 진행될 때 자동 ACK합니다.
+- `delete_queue()`, `delete_stream()`, `delete_exchange()`는 리소스를 삭제하므로
+  애플리케이션 소유 리소스에만 사용하세요.
+
+## 운영 시 주의사항
+
+- 최소 한 번(at-least-once) 전달을 전제로 멱등 작업을 작성하세요.
+- 무제한 재큐잉은 영구 오류 메시지의 반복 실행을 만들 수 있습니다. DLQ와 재시도 정책을 설계하세요.
+- 소비자 연결에서 긴 작업을 직접 실행하지 말고 Worker의 풀을 사용하세요.
+- 작업 훅에서 발행하려면 훅이 실행되는 스레드·프로세스 안에 별도 생산자 연결을 만드세요.
+- `worker.stop()`은 처리 중인 작업과 ACK를 기다린 뒤 연결과 풀을 닫습니다.
+  강제 종료 또는 종료 대기 시간 제한은 제공하지 않습니다.
+
+## 더 알아보기
+
+- [DefStream 사용 설명서](https://github.com/yong5eon/DefStream#readme): 작업, 풀, 훅, 검증, Inspector, 대시보드·콘솔
+- [큐·Exchange 예제](./sample/Sample.py)
+- [독립 실행 RPC 예제](./sample/Sample.RPC.py)
+- [스트림 예제](./sample/Sample.Stream.py)
+- [릴리즈와 변경 내역](https://github.com/yong5eon/DefStream-RabbitMQ/releases)
+
+GNU GPL v3 라이선스를 사용합니다. 자세한 조건은 [LICENSE](./LICENSE)를 확인하세요.