trackvault-shared 1.5.1

Shared utilities, services, and RBAC system for TrackVault microservices

TrackVault Shared Library

Shared utilities and services for TrackVault microservices.

⚠️ IMPORTANT: Maintaining GitHub-PyPI Integrity

When adding new features, fixing bugs, or making any changes to the shared library, you MUST follow this workflow to keep GitHub and PyPI in sync:

Workflow for Changes:

1. Make Your Changes

   • Edit code in the trackvault_shared/ directory
   • Update tests if needed
   • Test locally: pip install -e .

2. Update Version in pyproject.toml

   • Increment version number following Semantic Versioning:
     • PATCH (1.5.0 → 1.5.1): Bug fixes, minor updates
     • MINOR (1.5.0 → 1.6.0): New features, backward compatible
     • MAJOR (1.5.0 → 2.0.0): Breaking changes

   [project]
   version = "1.5.1"  # Update this!
   

3. Commit and Push to GitHub

   git add .
   git commit -m "Add new feature: [description]"
   git push origin main
   

4. Create GitHub Release (Triggers PyPI Publish)

   • Go to: https://github.com/muhsinbinirshad/trackvault-shared-lib/releases/new
   • Tag version: v1.5.1 (must match pyproject.toml version, must start with v)
   • Release title: TrackVault Shared Library v1.5.1
   • Description: Brief changelog of what changed
   • Click "Publish release"

5. GitHub Actions Automatically:

   • Builds the package from pyproject.toml
   • Publishes to PyPI with version from pyproject.toml
   • Creates a tagged release on GitHub

6. Verify Publication

   • Check PyPI: https://pypi.org/project/trackvault-shared/
   • Verify version appears: pip search trackvault-shared (or check PyPI web)
   • Test installation: pip install trackvault-shared==1.5.1

Critical Rules:

• ✅ ALWAYS update pyproject.toml version before creating a 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)
• ✅ Test locally first: pip install -e . in trackvault-shared-lib/
• ✅ Don't publish without version bump (PyPI rejects duplicate versions)
• ❌ Never push to PyPI manually (use GitHub Actions workflow only)
• ❌ Never skip version bump (causes version conflicts)

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.