offline-sync-sdk 0.2.0__tar.gz

offline_sync_sdk-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          version: "0.12.13"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --group dev --all-extras
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Run Ruff
+        if: matrix.python-version == '3.12'
+        run: uv run ruff check src tests benchmarks
+
+      - name: Run mypy
+        if: matrix.python-version == '3.12'
+        env:
+          MYPYPATH: src
+        run: uv run mypy src benchmarks/sync_throughput.py
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          version: "0.12.13"
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build --no-sources
+
+      - name: Check package metadata
+        run: uvx --from twine twine check dist/*
+
+      - name: Install and import wheel
+        run: |
+          uv venv /tmp/sync-sdk-wheel-check
+          uv pip install --python /tmp/sync-sdk-wheel-check/bin/python dist/*.whl
+          /tmp/sync-sdk-wheel-check/bin/python -c \
+            'import importlib.metadata as m; import sync_sdk; print(m.version("offline-sync-sdk"))'
+
+      - name: Save distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-distributions
+          path: dist/*

offline_sync_sdk-0.2.0/.github/workflows/database-adapters.yml

@@ -0,0 +1,204 @@
+name: Database adapters
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  live-sql:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: sync
+          POSTGRES_PASSWORD: sync
+          POSTGRES_DB: sync_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U sync -d sync_test"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+      mysql:
+        image: mysql:8.4
+        env:
+          MYSQL_DATABASE: sync_test
+          MYSQL_USER: sync
+          MYSQL_PASSWORD: sync
+          MYSQL_ROOT_PASSWORD: root
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -uroot -proot"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          version: "0.12.13"
+          enable-cache: true
+
+      - name: Install test dependencies
+        run: uv sync --locked --group dev --extra postgres --extra mysql
+
+      - name: Test adapters and collect metrics
+        env:
+          SYNC_TEST_POSTGRES_URL: postgresql+asyncpg://sync:sync@127.0.0.1:5432/sync_test
+          SYNC_TEST_MYSQL_URL: mysql+asyncmy://sync:sync@127.0.0.1:3306/sync_test
+          SYNC_TEST_METRICS_PATH: database-adapter-metrics.json
+        run: >-
+          uv run pytest tests/integration/test_sql_database_adapters.py
+          -q -s --junitxml=database-adapter-tests.xml
+
+      - name: Benchmark PostgreSQL throughput
+        env:
+          SYNC_TEST_POSTGRES_URL: postgresql+asyncpg://sync:sync@127.0.0.1:5432/sync_test
+        run: |
+          set -euo pipefail
+          for concurrency in 1 2 4 8; do
+            uv run python benchmarks/sync_throughput.py \
+              --database-url "$SYNC_TEST_POSTGRES_URL" \
+              --mutations 1000 \
+              --warmup 100 \
+              --batch-size 100 \
+              --concurrency "$concurrency" \
+              --fail-on-errors \
+              --output "benchmark-postgresql-c${concurrency}.json"
+          done
+
+      - name: Benchmark MySQL throughput
+        env:
+          SYNC_TEST_MYSQL_URL: mysql+asyncmy://sync:sync@127.0.0.1:3306/sync_test
+        run: |
+          set -euo pipefail
+          for concurrency in 1 2 4 8; do
+            uv run python benchmarks/sync_throughput.py \
+              --database-url "$SYNC_TEST_MYSQL_URL" \
+              --mutations 1000 \
+              --warmup 100 \
+              --batch-size 100 \
+              --concurrency "$concurrency" \
+              --fail-on-errors \
+              --output "benchmark-mysql-c${concurrency}.json"
+          done
+
+      - name: Show metric report
+        if: always()
+        run: |
+          if test -f database-adapter-metrics.json; then
+            {
+              echo '## Database adapter metrics'
+              echo '```json'
+              cat database-adapter-metrics.json
+              echo '```'
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+          for report in benchmark-*-c*.json; do
+            if test -f "$report"; then
+              {
+                echo "## $report"
+                echo '```json'
+                cat "$report"
+                echo '```'
+              } >> "$GITHUB_STEP_SUMMARY"
+            fi
+          done
+
+      - name: Save test reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: database-adapter-reports
+          path: |
+            database-adapter-metrics.json
+            database-adapter-tests.xml
+            benchmark-*-c*.json
+          if-no-files-found: ignore
+
+  live-mongodb:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          version: "0.12.13"
+          enable-cache: true
+
+      - name: Start MongoDB replica set
+        run: |
+          docker run --detach --name sync-mongodb --publish 27017:27017 \
+            mongo:8.0 --replSet rs0 --bind_ip_all
+          for attempt in $(seq 1 60); do
+            docker exec sync-mongodb mongosh --quiet \
+              --eval 'db.adminCommand({ping: 1}).ok' >/dev/null 2>&1 && break
+            test "$attempt" -lt 60 || exit 1
+            sleep 1
+          done
+          docker exec sync-mongodb mongosh --quiet --eval \
+            'rs.initiate({_id: "rs0", members: [{_id: 0, host: "localhost:27017"}]})'
+          for attempt in $(seq 1 60); do
+            docker exec sync-mongodb mongosh --quiet \
+              --eval 'db.hello().isWritablePrimary' | grep -q true && break
+            test "$attempt" -lt 60 || exit 1
+            sleep 1
+          done
+
+      - name: Install test dependencies
+        run: uv sync --locked --group dev --extra mongodb
+
+      - name: Test MongoDB adapter
+        env:
+          SYNC_TEST_MONGODB_URL: "mongodb://127.0.0.1:27017/sync_test?replicaSet=rs0&directConnection=true"
+        run: >-
+          uv run pytest tests/integration/test_mongodb_adapter.py
+          -q --junitxml=mongodb-adapter-tests.xml
+
+      - name: Benchmark MongoDB throughput
+        env:
+          SYNC_TEST_MONGODB_URL: "mongodb://127.0.0.1:27017/sync_test?replicaSet=rs0&directConnection=true"
+        run: |
+          set -euo pipefail
+          for concurrency in 1 2 4 8; do
+            uv run python benchmarks/sync_throughput.py \
+              --mongodb-url "$SYNC_TEST_MONGODB_URL" \
+              --mutations 1000 \
+              --warmup 100 \
+              --batch-size 100 \
+              --concurrency "$concurrency" \
+              --fail-on-errors \
+              --output "benchmark-mongodb-c${concurrency}.json"
+          done
+
+      - name: Show MongoDB benchmark reports
+        if: always()
+        run: |
+          for report in benchmark-mongodb-c*.json; do
+            if test -f "$report"; then
+              {
+                echo "## $report"
+                echo '```json'
+                cat "$report"
+                echo '```'
+              } >> "$GITHUB_STEP_SUMMARY"
+            fi
+          done
+
+      - name: Save MongoDB test report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: mongodb-adapter-report
+          path: |
+            mongodb-adapter-tests.xml
+            benchmark-mongodb-c*.json
+          if-no-files-found: ignore

offline_sync_sdk-0.2.0/.github/workflows/pypi.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.1.0
+        with:
+          version: "0.12.13"
+          enable-cache: true
+
+      - name: Verify release tag
+        run: |
+          package_version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "$GITHUB_REF_NAME" = "v$package_version"
+
+      - name: Build package
+        run: uv build --no-sources
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

offline_sync_sdk-0.2.0/.github/workflows/testpypi.yml

@@ -0,0 +1,33 @@
+name: Publish to TestPyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.1.0
+        with:
+          version: "0.12.13"
+          enable-cache: true
+
+      - name: Build package
+        run: uv build --no-sources
+
+      - name: Publish package to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

offline_sync_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+Notable changes to Sync SDK are recorded here. The project follows semantic
+versioning while allowing breaking API changes before version 1.0.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-16
+
+### Added
+
+- Transactional MongoDB adapter for replica sets and sharded clusters.
+- Polling SQL change capture for writes made outside the gateway.
+- Reproducible PostgreSQL, MySQL, MongoDB, and SQLite throughput benchmarks.
+- Database concurrency benchmarks with correctness auditing in GitHub Actions.
+- Benchmark results and concise comparison visuals.
+- MIT licensing and a DCO-based contribution policy.
+
+### Changed
+
+- Published under the `offline-sync-sdk` distribution name to avoid a production
+  PyPI name collision; the `sync_sdk` import package and `sync-sdk` command remain
+  unchanged.
+- Documented PostgreSQL as the recommended production gateway database.
+- Expanded database, packaging, observability, and deployment guidance.
+
+### Verified
+
+- PostgreSQL 16, MySQL 8.4, and MongoDB 8.0 completed the concurrency 1, 2, 4,
+  and 8 benchmark matrix with zero failed mutations.
+- The full local suite passed with 58 tests and 3 expected environment skips.
+
+[Unreleased]: https://github.com/VivekReddy10-08-2004/sync-sdk/compare/v0.2.0...HEAD

offline_sync_sdk-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thank you for improving Sync SDK. Bug reports, documentation fixes, tests, and
+focused code changes are welcome.
+
+## Before you start
+
+- Search existing issues and pull requests before opening a duplicate.
+- Open an issue before a large change so its behavior and scope can be agreed.
+- Report security problems privately as described in [SECURITY.md](SECURITY.md).
+
+## Make a change
+
+Sync SDK requires Python 3.12 or newer and uses `uv` for its development
+environment.
+
+```sh
+git clone https://github.com/VivekReddy10-08-2004/sync-sdk.git
+cd sync-sdk
+uv sync --locked --group dev --all-extras
+uv run pytest -q
+```
+
+Keep changes focused. Add tests when behavior changes, update the relevant
+documentation, and avoid committing credentials, local databases, generated
+environments, or benchmark results from an unrepeatable setup.
+
+Before opening a pull request, run:
+
+```sh
+uv run ruff check src tests benchmarks
+MYPYPATH=src uv run mypy src benchmarks/sync_throughput.py
+uv run pytest -q
+```
+
+Database-specific changes should also pass the relevant live adapter contract.
+The pull request workflow runs PostgreSQL, MySQL, and MongoDB services.
+
+## Commit certification and license
+
+This project uses the [Developer Certificate of Origin 1.1](https://developercertificate.org/)
+instead of a separate Contributor License Agreement. Add a `Signed-off-by` line
+to every commit with:
+
+```sh
+git commit --signoff
+```
+
+The sign-off certifies that you wrote the contribution, have the right to submit
+it, and understand that it is public. Use your real name and an email address you
+control. If needed, add a sign-off to your latest commit with
+`git commit --amend --signoff`.
+
+Contributions are accepted under the repository's [MIT License](LICENSE), using
+the same license for incoming contributions and outgoing releases. You retain
+copyright in your contribution. This policy does not transfer your copyright or
+give the project permission to relicense your work under incompatible terms.
+
+## Pull requests
+
+Explain the problem and resulting behavior, link related issues, and include the
+commands used for validation. Maintainers may ask for changes to keep the public
+API, storage guarantees, and documentation consistent.

offline_sync_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VivekReddy10-08-2004
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.