pactown 0.1.16__tar.gz → 0.1.47__tar.gz

{pactown-0.1.16 → pactown-0.1.47}/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.1.16
+current_version = 0.1.47
 commit = False
 tag = False
 

pactown-0.1.47/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-01-16
+
+### Added
+
+- **Fast Start Module** (`fast_start.py`)
+  - Dependency caching with hash-based venv reuse
+  - ~50-100ms startup for cached deps vs ~5-10s fresh
+  - `ServiceRunner.fast_run()` method
+  - Parallel file writing for sandbox creation
+
+- **Security Policy Module** (`security.py`)
+  - Rate limiting with token bucket algorithm
+  - User profiles with tier-based limits (FREE/BASIC/PRO/ENTERPRISE)
+  - Concurrent service limits per user
+  - Anomaly logging for admin monitoring
+  - Server load throttling
+
+- **User Isolation Module** (`user_isolation.py`)
+  - Linux user-based sandbox isolation
+  - Per-SaaS-user home directories
+  - Process isolation with different UIDs
+  - Export/import for user data migration
+  - REST API endpoints for user management
+
+- **Detailed Logging**
+  - Structured logging in sandbox_manager
+  - STDERR/STDOUT capture on process failure
+  - Signal interpretation (SIGTERM, SIGKILL, etc.)
+  - Per-service error log files
+
+- **New Documentation**
+  - `docs/FAST_START.md` - Dependency caching guide
+  - `docs/SECURITY_POLICY.md` - Rate limiting and user profiles
+  - `docs/USER_ISOLATION.md` - Multi-tenant isolation
+  - `docs/LOGGING.md` - Structured logging guide
+  - Navigation links across all docs
+
+- **New Examples**
+  - `examples/fast-start-demo/` - Fast startup with caching
+  - `examples/security-policy/` - Rate limiting demo
+  - `examples/user-isolation/` - Multi-tenant isolation demo
+
+### Changed
+
+- README.md restructured with feature menu and quick navigation
+- All docs updated with cross-links for easier navigation
+- sandbox_manager.py: Better error capture and signal handling
+- service_runner.py: Added delays to prevent race conditions on restart
+
+### Fixed
+
+- Process killed by SIGTERM on restart (race condition)
+- Truncated error output from crashed processes
+- **Hardcoded port mismatch** - Auto-replace hardcoded ports (e.g., `--port 8009`) with requested port
+- PORT and MARKPACT_PORT environment variables now always set
+
+## [Unreleased]
+
+### Added
+
+- Podman Quadlet deployment backend (`pactown.deploy.quadlet`) with templates, backend operations, and Traefik integration.
+- Interactive Quadlet shell (`pactown quadlet shell`).
+- Quadlet REST API (`pactown quadlet api`) and entrypoint `pactown-quadlet-api`.
+- Security hardening and injection test suite (`tests/test_quadlet_security.py`).
+- Quadlet security guide (`docs/SECURITY.md`).
+- Cloudflare Workers comparison (`docs/CLOUDFLARE_WORKERS_COMPARISON.md`).
+- Practical Quadlet examples in `examples/*` where the user edits only `README.md` (embedded code blocks) and deployment artifacts are generated into `./sandbox`.
+
+### Changed
+
+- Dockerfile Python healthcheck now uses `MARKPACT_PORT` with fallback to `PORT` to maintain compatibility.
+- Registry timestamps use timezone-aware datetimes (`datetime.now(timezone.utc)`) to avoid Python 3.13 deprecations.
+- Makefile:
+  - Prefers project venv python if present.
+  - `lint`/`format` fall back to `pipx run ruff` when ruff is not installed in the interpreter.
+  - `test` explicitly loads `pytest_asyncio.plugin` to work with `PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`.
+
+### Fixed
+
+- Multiple Quadlet injection vectors (container name, env var, volume, Traefik label, systemd unit) mitigated via input sanitization.
+- Ruff lint issues across `src/` and `tests/`.
+
+## [0.1.5]
+
+- Initial public version.

{pactown-0.1.16 → pactown-0.1.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pactown
-Version: 0.1.16
+Version: 0.1.47
 Summary: Decentralized Service Ecosystem Orchestrator - Build interconnected microservices from Markdown using markpact
 Project-URL: Homepage, https://github.com/wronai/pactown
 Project-URL: Repository, https://github.com/wronai/pactown
@@ -30,6 +30,8 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Requires-Dist: uvicorn>=0.20.0
 Requires-Dist: watchfiles>=0.20.0
+Provides-Extra: all
+Requires-Dist: lolm>=0.1.6; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: bump2version>=1.0; extra == 'dev'
@@ -38,6 +40,8 @@ Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1; extra == 'dev'
 Requires-Dist: twine; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: lolm>=0.1.6; extra == 'llm'
 Description-Content-Type: text/markdown
 
 ![img.png](img.png)

{pactown-0.1.16 → pactown-0.1.47}/docs/CONFIGURATION.md

@@ -1,6 +1,10 @@
 # Configuration Reference
 
-> **See also:** [README](../README.md) | [Specification](SPECIFICATION.md) | [Network](NETWORK.md) | [Generator](GENERATOR.md)
+[← Back to README](../README.md) | [Specification](SPECIFICATION.md) | [Network](NETWORK.md) | [Deployment →](DEPLOYMENT.md)
+
+---
+
+> **Related:** [Generator](GENERATOR.md) | [Fast Start](FAST_START.md) | [Security Policy](SECURITY_POLICY.md)
 
 Complete reference for `saas.pactown.yaml` configuration files.
 

{pactown-0.1.16 → pactown-0.1.47}/docs/DEPLOYMENT.md

@@ -1,6 +1,10 @@
 # Production Deployment Guide
 
-> **See also:** [README](../README.md) | [Specification](SPECIFICATION.md) | [Configuration](CONFIGURATION.md) | [Network](NETWORK.md) | [Quadlet](QUADLET.md) | [Security](SECURITY.md)
+[← Back to README](../README.md) | [Configuration](CONFIGURATION.md) | [Quadlet →](QUADLET.md)
+
+---
+
+> **Related:** [Network](NETWORK.md) | [Security](SECURITY.md) | [User Isolation](USER_ISOLATION.md)
 
 This guide covers deploying pactown ecosystems to production using Docker, Podman, and Kubernetes.
 

{pactown-0.1.16 → pactown-0.1.47}/docs/NETWORK.md

@@ -1,6 +1,10 @@
 # Network & Service Discovery
 
-> **See also:** [README](../README.md) | [Specification](SPECIFICATION.md) | [Configuration](CONFIGURATION.md) | [Generator](GENERATOR.md)
+[← Back to README](../README.md) | [Configuration](CONFIGURATION.md) | [Deployment →](DEPLOYMENT.md)
+
+---
+
+> **Related:** [Specification](SPECIFICATION.md) | [Generator](GENERATOR.md)
 
 This document describes pactown's dynamic port allocation and service discovery system.
 

{pactown-0.1.16 → pactown-0.1.47}/docs/SPECIFICATION.md

@@ -1,5 +1,9 @@
 # Pactown System Specification
 
+[← Back to README](../README.md) | [Configuration →](CONFIGURATION.md)
+
+---
+
 ## Problem Statement
 
 Modern software systems are increasingly composed of multiple independent services that need to work together. However, setting up and managing these systems presents several challenges:

pactown-0.1.47/examples/fast-start-demo/README.md

@@ -0,0 +1,82 @@
+# Fast Start Demo
+
+This example demonstrates pactown's fast startup capabilities with dependency caching.
+
+## What This Shows
+
+- **First run**: Dependencies are installed and cached (~5-10s)
+- **Second run**: Cached venv is reused (~50-100ms)
+- **Same deps = same cache**: Projects with identical dependencies share the cache
+
+## Files
+
+- `demo.py` - Python script demonstrating fast_run vs regular run
+- `api/README.md` - Sample FastAPI service
+- `api2/README.md` - Second service with same deps (will use cache)
+
+## Usage
+
+```bash
+# Run the demo
+python demo.py
+
+# Or use pactown CLI
+pactown up fast-start.pactown.yaml
+```
+
+## Expected Output
+
+```
+=== Fast Start Demo ===
+
+Run 1 (fresh):
+  Creating sandbox...
+  Installing dependencies (fastapi, uvicorn)...
+  ✓ Started in 5.2s
+
+Run 2 (cached):
+  ⚡ Cache hit! Reusing venv
+  ✓ Started in 0.08s
+
+Speedup: 65x faster!
+```
+
+## How It Works
+
+```python
+from pactown import ServiceRunner
+
+runner = ServiceRunner(enable_fast_start=True)
+
+# First run - creates and caches venv
+result1 = await runner.fast_run(
+    service_id="api-1",
+    content=open("api/README.md").read(),
+    port=8001,
+)
+
+# Second run - reuses cached venv
+result2 = await runner.fast_run(
+    service_id="api-2",
+    content=open("api2/README.md").read(),  # Same deps!
+    port=8002,
+)
+```
+
+## Cache Location
+
+```
+/tmp/pactown-sandboxes/
+├── .cache/
+│   └── venvs/
+│       └── venv_a1b2c3d4/    # Cached: fastapi + uvicorn
+├── api-1/
+│   └── .venv -> ../.cache/venvs/venv_a1b2c3d4
+└── api-2/
+    └── .venv -> ../.cache/venvs/venv_a1b2c3d4  # Same cache!
+```
+
+## Related Documentation
+
+- [Fast Start Guide](../../docs/FAST_START.md)
+- [Security Policy](../../docs/SECURITY_POLICY.md)

pactown-0.1.47/examples/fast-start-demo/demo.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Fast Start Demo - Demonstrates dependency caching for fast startup.
+
+Usage:
+    python demo.py
+"""
+import asyncio
+import time
+from pathlib import Path
+
+# Add pactown to path if running from source
+import sys
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
+
+from pactown import ServiceRunner
+
+
+API_README = '''# Demo API
+
+Simple FastAPI service for demonstrating fast start.
+
+```python markpact:deps
+fastapi
+uvicorn
+```
+
+```python markpact:file path=main.py
+from fastapi import FastAPI
+
+app = FastAPI(title="Fast Start Demo")
+
+@app.get("/")
+def root():
+    return {"message": "Hello from Fast Start Demo!"}
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+```
+
+```bash markpact:run
+uvicorn main:app --host 0.0.0.0 --port $PORT
+```
+'''
+
+
+async def main():
+    print("=" * 50)
+    print("⚡ Fast Start Demo")
+    print("=" * 50)
+    print()
+    
+    runner = ServiceRunner(
+        sandbox_root="/tmp/fast-start-demo",
+        enable_fast_start=True,
+    )
+    
+    # Run 1 - First run (cold start)
+    print("Run 1 (fresh install):")
+    print("  Creating sandbox and installing dependencies...")
+    
+    start = time.time()
+    result1 = await runner.fast_run(
+        service_id="demo-api-1",
+        content=API_README,
+        port=10091,
+    )
+    time1 = time.time() - start
+    
+    if result1.success:
+        print(f"  ✓ Started in {time1:.2f}s")
+    else:
+        print(f"  ❌ Failed: {result1.message}")
+        return
+    
+    # Stop first service
+    runner.stop("demo-api-1")
+    
+    print()
+    
+    # Run 2 - Second run (cache hit)
+    print("Run 2 (cached):")
+    print("  ⚡ Checking cache...")
+    
+    start = time.time()
+    result2 = await runner.fast_run(
+        service_id="demo-api-2",
+        content=API_README,  # Same deps!
+        port=10092,
+    )
+    time2 = time.time() - start
+    
+    if result2.success:
+        print(f"  ✓ Started in {time2:.2f}s")
+    else:
+        print(f"  ❌ Failed: {result2.message}")
+    
+    # Stop second service
+    runner.stop("demo-api-2")
+    
+    print()
+    print("=" * 50)
+    print(f"Results:")
+    print(f"  First run:  {time1:.2f}s")
+    print(f"  Second run: {time2:.2f}s")
+    if time2 > 0:
+        print(f"  Speedup:    {time1/time2:.1f}x faster!")
+    print("=" * 50)
+    
+    # Show cache stats
+    stats = runner.get_cache_stats()
+    print()
+    print("Cache Statistics:")
+    print(f"  Entries: {stats.get('cache_entries', 0)}")
+    print(f"  Caching enabled: {stats.get('caching_enabled', False)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pactown-0.1.47/examples/security-policy/README.md

@@ -0,0 +1,92 @@
+# Security Policy Demo
+
+This example demonstrates pactown's security policy features for multi-tenant SaaS.
+
+## What This Shows
+
+- **Rate limiting** - Token bucket algorithm to prevent abuse
+- **User profiles** - Tier-based resource limits (FREE/BASIC/PRO)
+- **Concurrent limits** - Max services per user
+- **Anomaly logging** - Track and alert on security events
+
+## Files
+
+- `demo.py` - Python script demonstrating security features
+- `multi_tenant.py` - Multi-tenant SaaS simulation
+
+## Usage
+
+```bash
+# Run the demo
+python demo.py
+
+# Or run the multi-tenant simulation
+python multi_tenant.py
+```
+
+## Expected Output
+
+```
+=== Security Policy Demo ===
+
+Creating user profiles...
+  ✓ free_user (FREE tier): max 2 concurrent services
+  ✓ pro_user (PRO tier): max 10 concurrent services
+
+Testing rate limiting...
+  Request 1: ✓ allowed
+  Request 2: ✓ allowed
+  ...
+  Request 21: ✗ rate limited (wait 2.5s)
+
+Testing concurrent limits...
+  free_user starting service 1: ✓ allowed
+  free_user starting service 2: ✓ allowed
+  free_user starting service 3: ✗ limit reached (2/2)
+
+Anomaly log:
+  [RATE_LIMIT_EXCEEDED] free_user - Rate limit exceeded
+  [CONCURRENT_LIMIT_EXCEEDED] free_user - Max 2 services
+```
+
+## User Tiers
+
+| Tier | Concurrent | Memory | Requests/min |
+|------|------------|--------|--------------|
+| FREE | 2 | 256MB | 20 |
+| BASIC | 5 | 512MB | 60 |
+| PRO | 10 | 2GB | 120 |
+| ENTERPRISE | 50 | 8GB | 500 |
+
+## Code Example
+
+```python
+from pactown import SecurityPolicy, UserProfile, UserTier
+
+# Create security policy
+policy = SecurityPolicy(
+    anomaly_log_path=Path("./anomalies.jsonl"),
+    default_rate_limit=60,
+)
+
+# Create user profile
+profile = UserProfile.from_tier("user123", UserTier.PRO)
+policy.set_user_profile(profile)
+
+# Check if user can start service
+result = await policy.check_can_start_service(
+    user_id="user123",
+    service_id="my-api",
+    port=8001,
+)
+
+if result.allowed:
+    print("✓ Starting service...")
+else:
+    print(f"✗ Denied: {result.reason}")
+```
+
+## Related Documentation
+
+- [Security Policy Guide](../../docs/SECURITY_POLICY.md)
+- [User Isolation](../../docs/USER_ISOLATION.md)

pactown-0.1.47/examples/security-policy/demo.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+Security Policy Demo - Demonstrates rate limiting and user profiles.
+
+Usage:
+    python demo.py
+"""
+import asyncio
+from pathlib import Path
+
+# Add pactown to path if running from source
+import sys
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
+
+from pactown import SecurityPolicy, UserProfile, UserTier, AnomalyType
+
+
+async def main():
+    print("=" * 50)
+    print("🛡️  Security Policy Demo")
+    print("=" * 50)
+    print()
+    
+    # Create security policy
+    policy = SecurityPolicy(
+        anomaly_log_path=Path("./demo_anomalies.jsonl"),
+        default_rate_limit=20,  # 20 requests per minute for demo
+        cpu_threshold=80.0,
+        memory_threshold=85.0,
+    )
+    
+    # Create user profiles
+    print("Creating user profiles...")
+    
+    free_user = UserProfile.from_tier("free_user", UserTier.FREE)
+    pro_user = UserProfile.from_tier("pro_user", UserTier.PRO)
+    
+    policy.set_user_profile(free_user)
+    policy.set_user_profile(pro_user)
+    
+    print(f"  ✓ free_user (FREE): max {free_user.max_concurrent_services} services, {free_user.max_requests_per_minute} req/min")
+    print(f"  ✓ pro_user (PRO): max {pro_user.max_concurrent_services} services, {pro_user.max_requests_per_minute} req/min")
+    print()
+    
+    # Test rate limiting
+    print("Testing rate limiting (free_user)...")
+    
+    for i in range(25):
+        result = await policy.check_can_start_service(
+            user_id="free_user",
+            service_id=f"test-service-{i}",
+            port=10000 + i,
+        )
+        
+        if result.allowed:
+            print(f"  Request {i+1}: ✓ allowed")
+        else:
+            print(f"  Request {i+1}: ✗ {result.reason}")
+            if result.wait_seconds:
+                print(f"             Wait {result.wait_seconds:.1f}s before retry")
+            break
+    
+    print()
+    
+    # Test concurrent limits
+    print("Testing concurrent service limits (free_user)...")
+    
+    # Simulate starting services
+    for i in range(4):
+        service_id = f"concurrent-test-{i}"
+        
+        # Check if allowed
+        result = await policy.check_can_start_service(
+            user_id="free_user",
+            service_id=service_id,
+            port=11000 + i,
+        )
+        
+        if result.allowed:
+            # Register the service as running
+            policy.register_service("free_user", service_id)
+            count = policy.get_user_service_count("free_user")
+            print(f"  Service {i+1}: ✓ started (running: {count}/{free_user.max_concurrent_services})")
+        else:
+            print(f"  Service {i+1}: ✗ {result.reason}")
+    
+    print()
+    
+    # Show anomaly summary
+    print("Anomaly summary:")
+    summary = policy.get_anomaly_summary(hours=1)
+    print(f"  Total events: {summary.get('total_count', 0)}")
+    
+    by_type = summary.get('by_type', {})
+    for anomaly_type, count in by_type.items():
+        print(f"  - {anomaly_type}: {count}")
+    
+    print()
+    print("=" * 50)
+    print("Demo complete! Check demo_anomalies.jsonl for logged events.")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pactown-0.1.47/examples/user-isolation/README.md

@@ -0,0 +1,94 @@
+# User Isolation Demo
+
+This example demonstrates pactown's Linux user-based sandbox isolation for multi-tenant SaaS.
+
+## What This Shows
+
+- **Linux user creation** - Each SaaS user gets a dedicated Linux user
+- **Process isolation** - Different UIDs prevent cross-tenant access
+- **File isolation** - Separate home directories per user
+- **Migration support** - Export/import user data
+
+## Files
+
+- `demo.py` - Python script demonstrating user isolation
+- `migration.py` - Demonstrates user data migration
+
+## Usage
+
+```bash
+# Run the demo (works in non-root mode too)
+python demo.py
+
+# Run migration demo
+python migration.py
+```
+
+## Expected Output
+
+```
+=== User Isolation Demo ===
+
+Creating isolated users...
+  ✓ user_alice -> pactown_a1b2c3d4 (UID: 60001)
+  ✓ user_bob -> pactown_e5f6g7h8 (UID: 60002)
+
+Creating sandboxes...
+  ✓ user_alice/my-api: /home/pactown_users/pactown_a1b2c3d4/sandboxes/my-api
+  ✓ user_bob/my-api: /home/pactown_users/pactown_e5f6g7h8/sandboxes/my-api
+
+User statistics:
+  user_alice: 1 sandbox, 0.5 MB
+  user_bob: 1 sandbox, 0.5 MB
+
+Total isolated users: 2
+```
+
+## Architecture
+
+```
+/home/pactown_users/
+├── pactown_a1b2c3d4/         # user_alice (UID 60001)
+│   ├── sandboxes/
+│   │   └── my-api/
+│   │       ├── main.py
+│   │       └── .venv/
+│   └── .cache/
+└── pactown_e5f6g7h8/         # user_bob (UID 60002)
+    ├── sandboxes/
+    │   └── my-api/
+    └── .cache/
+```
+
+## Code Example
+
+```python
+from pactown import UserIsolationManager, get_isolation_manager
+
+# Get global manager
+manager = get_isolation_manager()
+
+# Create isolated user
+user = manager.get_or_create_user("alice@example.com")
+print(f"Linux user: {user.linux_username}")
+print(f"UID: {user.linux_uid}")
+print(f"Home: {user.home_dir}")
+
+# Get sandbox path
+sandbox = manager.get_sandbox_path("alice@example.com", "my-api")
+
+# Run command as isolated user
+process = manager.run_as_user(
+    saas_user_id="alice@example.com",
+    command="python main.py",
+    cwd=sandbox,
+)
+
+# Export for migration
+manager.export_user_data("alice@example.com", Path("/backup/alice.tar.gz"))
+```
+
+## Related Documentation
+
+- [User Isolation Guide](../../docs/USER_ISOLATION.md)
+- [Security Policy](../../docs/SECURITY_POLICY.md)