Python functions as REST objects, with clustering, load balancing and state replication; no containers or orchestration.
- api
- docs
- examples
- packages
- src
- tests
- .env.example 861 bytes
- .gitignore 733 bytes
- CHANGELOG.md 1.1 KB
- CONTRIBUTING.md 1.4 KB
- GUIDE.md 22.5 KB
- LICENSE 1.1 KB
- QUICKSTART.md 4.3 KB
- README.md 4.7 KB
- SECURITY.md 885 bytes
- cluster.example.tsv 561 bytes
- cluster.py 7.9 KB
- cluster_config.py 4.1 KB
- cluster_heartbeat_daemon.py 5.2 KB
- cluster_shell_helper.py 1.3 KB
- deploy.sh 1.0 KB
- process_manager.py 5.1 KB
- pyproject.toml 4.0 KB
- requirements-ocr.txt 720 bytes
- requirements.txt 549 bytes
- restart_cluster.sh 1.4 KB
- run_server.py 1.6 KB
- server.sh 1.8 KB
- start_cluster.sh 1.9 KB
- stop_cluster.sh 766 bytes
- test_api.py 6.9 KB
- test_auth.py 8.1 KB
- test_blog.py 10.7 KB
- test_composition.py 5.2 KB
- test_log_replication_live.py 1.3 KB
- test_state_replication_live.py 5.7 KB
- test_state_replication_simple.py 3.1 KB
- test_versioning.py 6.1 KB
Object Primitive
A distributed computing system that treats computation as objects with REST APIs. Write a Python function, get automatic clustering, load balancing, and state replication.
What We Accomplished
This system demonstrates that distributed computing doesn't require containers, orchestration platforms, or complex microservices frameworks. We built:
Phase 1-6: Core Runtime
- Object-as-API: Python functions become REST endpoints automatically
- State management: TSV-based persistence with versioning
- Self-logging: Queryable event logs built-in
- Version control: Track object code changes over time
Phase 7: Distributed Computing
- Automatic Clustering: Self-organizing multi-station mesh
- Cross-Station Calls: Objects call each other across the network transparently
- Object Migration: Move running objects between stations on demand
- Load-Aware Routing: Application-layer load balancing using actual CPU/memory metrics
- State Replication: Automatic async replication with last-write-wins conflict resolution
What It Replaces
| Traditional Stack | Object Primitive |
|---|---|
| Docker + Kubernetes | Built-in runtime |
| F5 Load Balancer | Automatic load routing |
| Redis/Memcached | Built-in state management |
| RabbitMQ/Kafka | Cross-object calls |
| Service mesh | Automatic routing |
Total cost comparison: Traditional stack $100k+/year vs $0 for Object Primitive.
Current Status
⚠️ NON-PRODUCTION USE ONLY
This is a research prototype demonstrating distributed computing primitives. It is not production-ready.
Known limitations:
- No built-in authentication/authorization: The runtime doesn't enforce auth (though you can build it as objects - see
examples/advanced/auth.py) - No permissions system: No access control enforced by the runtime
- No rate limiting: Objects can be overwhelmed
- No encryption: All communication is plaintext HTTP
- No input validation: Runtime trusts all incoming data
- No resource limits: Objects can consume unlimited memory/CPU
Before production use, we need:
- Runtime-level authentication and authorization enforcement
- Fine-grained permissions system (object-to-object, user-to-object)
- Resource quotas and limits
- TLS/encryption for network communication
- Input validation and sanitization
- Rate limiting and DoS protection
- Audit logging for security events
Quick Start
Single Station
# Install dependencies
python3 -m pip install -r requirements.txt
# Run server
python run_server.py
Server runs on http://localhost:8001
Create an Object
# examples/hello.py
def GET(request):
return {"message": "Hello, World!"}
Call It
curl http://localhost:8001/objects/hello
# {"message": "Hello, World!"}
Run a Cluster
- Copy the example configuration:
cp cluster.example.tsv cluster.tsv
- Edit
cluster.tsvwith your station IPs:
station_id host port user role
station1 192.168.1.10 8001 youruser master
station2 192.168.1.11 8001 youruser worker
station3 192.168.1.12 8001 youruser worker
- Start the cluster:
./start_cluster.sh
Objects automatically distribute across stations based on load.
Examples
See examples/ directory:
- basics/counter.py - Stateful counter
- tutorial/04_calculator.py - Stateful calculator with operations
- advanced/auth.py - User authentication (450 lines, complete system)
- advanced/blog.py - Blog with posts, tags, pagination (400 lines)
Architecture
- No Containers: Direct Python execution
- No Config Files: Just write Python functions
- No Database: State in TSV files (human-readable, git-friendly)
- No Orchestration: Self-organizing cluster
- No Service Discovery: Built into runtime
How It Works
- Write a Python function with HTTP method names (GET, POST, etc.)
- Runtime loads it and exposes as REST API
- Functions get
_state_manager,_logger,_runtimeinjected - State persists automatically across requests
- In cluster mode, runtime handles routing and replication
Performance Notes
- Zero serialization overhead for local calls
- Async state replication (doesn't block requests)
- Load-based routing (CPU/memory aware)
- No container tax
License
MIT License - see LICENSE file
Contributing
This is a research prototype. We're demonstrating concepts, not building a product (yet).
Issues and discussions welcome at: https://github.com/askrobots/dbbasic-object-primitive
See CONTRIBUTING.md for bug-report and PR guidance, and SECURITY.md for the private vulnerability reporting channel.
Built by Ask Robots / dbbasic.com
Making distributed computing simple again.