trackvault-shared 1.5.5

Shared utilities, services, and RBAC system for TrackVault microservices

TrackVault Shared Library

Shared utilities and services for TrackVault microservices.

⚠️ SIMPLE STEP-BY-STEP GUIDE: Editing Shared Library

After you edit code in the shared library, follow these steps EXACTLY:

Step 1: Edit Your Code

# Make changes in trackvault_shared/ directory
# Test locally (optional but recommended)
cd trackvault-shared-lib
pip install -e .

Step 2: Update Version in pyproject.toml ⚠️ CRITICAL!

⚠️ YOU MUST UPDATE VERSION EVEN IF YOU ONLY CHANGED README!

Open pyproject.toml and change the version:

[project]
version = "1.5.2"  # Change this number! (e.g., 1.5.1 → 1.5.2)

Why? PyPI rejects duplicate versions. If version 1.5.1 already exists, you cannot publish it again, even if only README changed.

Version Rules:

• 1.5.1 → 1.5.2 (bug fix, README update, docs only)
• 1.5.1 → 1.6.0 (new feature, backward compatible)
• 1.5.1 → 2.0.0 (breaking change)

Step 3: Commit and Push

git add .
git commit -m "Your commit message"
git push origin main

Step 4: Publish to PyPI (Choose ONE method):

Option A: Manually Trigger Workflow (EASIER!) ⭐ Recommended

1. Go to: https://github.com/muhsinbinirshad/trackvault-shared-lib/actions/workflows/publish.yml
2. Click "Run workflow" button (top right)
3. Select branch: main
4. Click "Run workflow" ✅

What happens:

• ✅ Reads version from pyproject.toml automatically (e.g., 1.5.1)
• ✅ Builds package with that version
• ✅ Publishes to PyPI automatically
• ✅ Creates tag v1.5.1 automatically (if it doesn't exist)
• ✅ Takes 1-2 minutes

No need to create a release! Just click "Run workflow" and it publishes to PyPI.

Option B: Create GitHub Release (If you want a visible release)

1. Go to: https://github.com/muhsinbinirshad/trackvault-shared-lib/releases/new
2. Click "Choose a tag" → Type: v1.5.1 (must match pyproject.toml version with v prefix!)
3. Release title: TrackVault Shared Library v1.5.1
4. Description: What you changed
5. Click "Publish release" ✅

What happens:

• ✅ Same as Option A (publishes to PyPI)
• ✅ PLUS creates a visible release on GitHub

Step 5: Wait 1-2 Minutes

The workflow automatically:

• ✅ Builds package from pyproject.toml
• ✅ Reads version from pyproject.toml (e.g., 1.5.1)
• ✅ Publishes to PyPI with that version

You don't need to do anything else!

Step 6: Verify (Optional)

• Check workflow: https://github.com/muhsinbinirshad/trackvault-shared-lib/actions
• Check PyPI: https://pypi.org/project/trackvault-shared/
• New version should appear automatically (1-2 minutes after workflow completes)

What About Microservices?

✅ Nothing to update! Microservices use trackvault-shared>=1.5.0, so they automatically get the new version (1.5.1) when you:

• Reinstall: pip install -r requirements.txt
• Or rebuild Docker images

Critical Rules:

• ✅ ALWAYS update pyproject.toml version FIRST (before running workflow)
• ✅ Even if you only changed README, you MUST bump version (PyPI rejects duplicates)
• ✅ Workflow reads version from pyproject.toml automatically (no need to specify tag manually)
• ✅ Workflow checks if version exists on PyPI and fails early (prevents upload errors)
• ✅ Test locally first: pip install -e . in trackvault-shared-lib/
• ❌ Never push to PyPI manually (use GitHub Actions workflow only)
• ❌ Never skip version bump (workflow will fail with clear error message)

What If You Forget to Update Version?

Don't worry! The workflow checks if the version already exists on PyPI and fails early with a clear error message:

⚠️ WARNING: Version 1.5.1 already exists on PyPI!
You must update version in pyproject.toml before publishing.
Current version in pyproject.toml: 1.5.1

To fix:

1. Update version in pyproject.toml (e.g., 1.5.1 → 1.5.2)
2. Commit and push: git add pyproject.toml && git commit -m 'Bump version' && git push
3. Run workflow again ✅

If using Option B (GitHub Release):

• ✅ Tag version MUST match pyproject.toml version (with v prefix)
• ✅ Tag format: v1.5.1 (not 1.5.1 or v1.5.0 if version is 1.5.1)

After Publishing:

• Update Microservices (if needed):
  • Update requirements.txt in microservices: trackvault-shared>=1.5.1
  • Or let them auto-update: trackvault-shared>=1.5.0 (will get 1.5.1)

Quick Checklist:

[ ] Made code changes
[ ] Updated version in pyproject.toml
[ ] Tested locally: pip install -e .
[ ] Committed and pushed to GitHub
[ ] Created GitHub release with matching tag (v1.x.x)
[ ] Verified GitHub Actions workflow succeeded
[ ] Verified package on PyPI
[ ] Updated microservices if needed

---

🚀 Quick Installation

Option 1: Install from PyPI (Recommended for Production)

# Install from PyPI
pip install trackvault-shared>=1.5.0

Benefits:

• ✅ Standard Python package installation
• ✅ Versioned releases
• ✅ Works in any environment
• ✅ CI/CD friendly
• ✅ No authentication required (public package)

Option 2: Install Locally (Development Only)

For local development, install in editable mode:

# From backend/ directory
cd backend
pip install -e ../trackvault-shared-lib

Benefits:

• ✅ Changes are immediately available (no reinstall needed)
• ✅ Perfect for active development

Note: For production/CI/CD, use PyPI (Option 1).

Features

• Event Bus: Redis Streams-based event publishing and subscription
• Plans Registry: Multi-tenancy plan definitions and validation
• Health Checks: Comprehensive health monitoring utilities
• Circuit Breaker: Prevent cascade failures
• Retry Pattern: Exponential backoff for resilient operations
• Event Schemas: Standardized event types for microservice communication
• Soft Delete: Soft delete mixins for Beanie models

Quick Start

from trackvault_shared import get_project_event_bus, PLANS

# Event Bus
bus = get_project_event_bus("redis://localhost:6379/0")
await bus.publish("project.created", {"project_id": "123"})

# Plans Registry
plan = get_plan_by_name("team")
print(plan["workspace_limits"])

📚 Publishing

To publish a new version:

1. Update version in pyproject.toml
2. Create a GitHub release (tag: v1.5.0)
3. GitHub Actions automatically publishes to PyPI

PyPI API Token Setup:

1. Go to https://pypi.org/manage/account/token/
2. Create API token with "Upload packages" scope
3. Add as secret PYPI_API_TOKEN in GitHub repository settings

License

MIT License - see LICENSE file for details.