sharedots 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sharedots-0.1.0/PKG-INFO +107 -0
- sharedots-0.1.0/README.md +90 -0
- sharedots-0.1.0/pyproject.toml +33 -0
- sharedots-0.1.0/setup.cfg +4 -0
- sharedots-0.1.0/setup.py +8 -0
- sharedots-0.1.0/sharedots/__init__.py +30 -0
- sharedots-0.1.0/sharedots/client.py +155 -0
- sharedots-0.1.0/sharedots/crypto.py +44 -0
- sharedots-0.1.0/sharedots/exceptions.py +48 -0
- sharedots-0.1.0/sharedots/future.py +156 -0
- sharedots-0.1.0/sharedots/remote.py +229 -0
- sharedots-0.1.0/sharedots/room.py +152 -0
- sharedots-0.1.0/sharedots/runner.py +111 -0
- sharedots-0.1.0/sharedots.egg-info/PKG-INFO +107 -0
- sharedots-0.1.0/sharedots.egg-info/SOURCES.txt +22 -0
- sharedots-0.1.0/sharedots.egg-info/dependency_links.txt +1 -0
- sharedots-0.1.0/sharedots.egg-info/entry_points.txt +2 -0
- sharedots-0.1.0/sharedots.egg-info/requires.txt +6 -0
- sharedots-0.1.0/sharedots.egg-info/top_level.txt +1 -0
- sharedots-0.1.0/tests/test_crypto.py +58 -0
- sharedots-0.1.0/tests/test_future.py +116 -0
- sharedots-0.1.0/tests/test_remote.py +95 -0
- sharedots-0.1.0/tests/test_runner.py +84 -0
- sharedots-0.1.0/tests/test_stress_failure.py +372 -0
sharedots-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sharedots
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Universal Distributed Compute Network — Python SDK & Remote Execution
|
|
5
|
+
Author: Sharedots Team
|
|
6
|
+
License: MIT
|
|
7
|
+
Classifier: Programming Language :: Python :: 3
|
|
8
|
+
Classifier: Topic :: System :: Distributed Computing
|
|
9
|
+
Requires-Python: >=3.9
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
Provides-Extra: dev
|
|
12
|
+
Requires-Dist: cloudpickle>=3.0.0; extra == "dev"
|
|
13
|
+
Requires-Dist: numpy>=1.24.0; extra == "dev"
|
|
14
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
15
|
+
Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
|
|
16
|
+
Dynamic: requires-python
|
|
17
|
+
|
|
18
|
+
# Sharedots Python SDK (`sharedots`)
|
|
19
|
+
|
|
20
|
+
Universal Distributed Compute Network — Python SDK & Remote Execution Engine.
|
|
21
|
+
|
|
22
|
+
The Sharedots Python SDK provides an intuitive, high-performance distributed computing interface with zero-boilerplate remote function execution. It seamlessly connects with the native Sharedots Coordinator and Rust worker daemons over Tailscale mesh networks or local subnets.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 🚀 Quickstart
|
|
27
|
+
|
|
28
|
+
### 1. Connect to a Compute Room
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
import sharedots as sd
|
|
32
|
+
|
|
33
|
+
# Connect to an existing room (e.g. over Tailscale or localhost)
|
|
34
|
+
client = sd.Client(
|
|
35
|
+
coordinator="http://100.82.14.30:4000",
|
|
36
|
+
room_id="room-alpha-123",
|
|
37
|
+
token="secret-token-xyz"
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
# Or create a new room directly:
|
|
41
|
+
room = client.create_room(name="my-mesh-room")
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### 2. Distribute Functions with `@client.remote`
|
|
45
|
+
|
|
46
|
+
Decorate any Python function to execute across remote cluster nodes:
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
import numpy as np
|
|
50
|
+
import sharedots as sd
|
|
51
|
+
|
|
52
|
+
client = sd.Client(coordinator="http://localhost:4000", room_id="room-1", token="secret")
|
|
53
|
+
|
|
54
|
+
@client.remote(cpu=2, memory="1GB", gpu=True)
|
|
55
|
+
def matrix_dot(a, b):
|
|
56
|
+
# Runs remotely on a cluster worker node
|
|
57
|
+
return np.dot(a, b)
|
|
58
|
+
|
|
59
|
+
# Dispatches task across the cluster and immediately returns a Future
|
|
60
|
+
future = matrix_dot(np.eye(100), np.eye(100))
|
|
61
|
+
|
|
62
|
+
# Await result
|
|
63
|
+
result = future.result(timeout=30)
|
|
64
|
+
print("Computed result:", result)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### 3. Parallel Sharded Batch Processing with `.map()`
|
|
68
|
+
|
|
69
|
+
Distribute array slices or parameter sweeps across all available worker nodes in a single job:
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
@client.remote(cpu=1, memory="512MB")
|
|
73
|
+
def evaluate_trial(trial_id, parameter):
|
|
74
|
+
import time
|
|
75
|
+
# Simulate simulation / training trial
|
|
76
|
+
return {"trial": trial_id, "score": parameter ** 2}
|
|
77
|
+
|
|
78
|
+
# Automatically shards tasks across all cluster workers in parallel:
|
|
79
|
+
trials = [(i, i * 0.1) for i in range(20)]
|
|
80
|
+
results = evaluate_trial.map(trials)
|
|
81
|
+
|
|
82
|
+
print("All trials completed:", results)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### 4. Gather Multiple Futures
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
futures = [matrix_dot(A_i, B) for A_i in slices]
|
|
89
|
+
results = sd.gather(futures)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### 5. Local Debugging with `.local()`
|
|
93
|
+
|
|
94
|
+
Test functions locally in your process without sending them to the network:
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
local_result = matrix_dot.local(np.eye(10), np.eye(10))
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 🔒 Security & Sandboxing
|
|
103
|
+
|
|
104
|
+
Unlike naive pickle RPC scripts, Sharedots executes remote functions inside:
|
|
105
|
+
1. Signed manifests verified by the Coordinator using **HMAC-SHA256**.
|
|
106
|
+
2. Sandboxed worker processes supervised by the **Rust Daemon** (`sharedots-daemon`) with scrubbed environment variables and process-tree watchdogs.
|
|
107
|
+
3. Content-addressed, SHA-256 verified chunked HTTP Range artifact caching.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Sharedots Python SDK (`sharedots`)
|
|
2
|
+
|
|
3
|
+
Universal Distributed Compute Network — Python SDK & Remote Execution Engine.
|
|
4
|
+
|
|
5
|
+
The Sharedots Python SDK provides an intuitive, high-performance distributed computing interface with zero-boilerplate remote function execution. It seamlessly connects with the native Sharedots Coordinator and Rust worker daemons over Tailscale mesh networks or local subnets.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 🚀 Quickstart
|
|
10
|
+
|
|
11
|
+
### 1. Connect to a Compute Room
|
|
12
|
+
|
|
13
|
+
```python
|
|
14
|
+
import sharedots as sd
|
|
15
|
+
|
|
16
|
+
# Connect to an existing room (e.g. over Tailscale or localhost)
|
|
17
|
+
client = sd.Client(
|
|
18
|
+
coordinator="http://100.82.14.30:4000",
|
|
19
|
+
room_id="room-alpha-123",
|
|
20
|
+
token="secret-token-xyz"
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
# Or create a new room directly:
|
|
24
|
+
room = client.create_room(name="my-mesh-room")
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### 2. Distribute Functions with `@client.remote`
|
|
28
|
+
|
|
29
|
+
Decorate any Python function to execute across remote cluster nodes:
|
|
30
|
+
|
|
31
|
+
```python
|
|
32
|
+
import numpy as np
|
|
33
|
+
import sharedots as sd
|
|
34
|
+
|
|
35
|
+
client = sd.Client(coordinator="http://localhost:4000", room_id="room-1", token="secret")
|
|
36
|
+
|
|
37
|
+
@client.remote(cpu=2, memory="1GB", gpu=True)
|
|
38
|
+
def matrix_dot(a, b):
|
|
39
|
+
# Runs remotely on a cluster worker node
|
|
40
|
+
return np.dot(a, b)
|
|
41
|
+
|
|
42
|
+
# Dispatches task across the cluster and immediately returns a Future
|
|
43
|
+
future = matrix_dot(np.eye(100), np.eye(100))
|
|
44
|
+
|
|
45
|
+
# Await result
|
|
46
|
+
result = future.result(timeout=30)
|
|
47
|
+
print("Computed result:", result)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### 3. Parallel Sharded Batch Processing with `.map()`
|
|
51
|
+
|
|
52
|
+
Distribute array slices or parameter sweeps across all available worker nodes in a single job:
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
@client.remote(cpu=1, memory="512MB")
|
|
56
|
+
def evaluate_trial(trial_id, parameter):
|
|
57
|
+
import time
|
|
58
|
+
# Simulate simulation / training trial
|
|
59
|
+
return {"trial": trial_id, "score": parameter ** 2}
|
|
60
|
+
|
|
61
|
+
# Automatically shards tasks across all cluster workers in parallel:
|
|
62
|
+
trials = [(i, i * 0.1) for i in range(20)]
|
|
63
|
+
results = evaluate_trial.map(trials)
|
|
64
|
+
|
|
65
|
+
print("All trials completed:", results)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### 4. Gather Multiple Futures
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
futures = [matrix_dot(A_i, B) for A_i in slices]
|
|
72
|
+
results = sd.gather(futures)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### 5. Local Debugging with `.local()`
|
|
76
|
+
|
|
77
|
+
Test functions locally in your process without sending them to the network:
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
local_result = matrix_dot.local(np.eye(10), np.eye(10))
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## 🔒 Security & Sandboxing
|
|
86
|
+
|
|
87
|
+
Unlike naive pickle RPC scripts, Sharedots executes remote functions inside:
|
|
88
|
+
1. Signed manifests verified by the Coordinator using **HMAC-SHA256**.
|
|
89
|
+
2. Sandboxed worker processes supervised by the **Rust Daemon** (`sharedots-daemon`) with scrubbed environment variables and process-tree watchdogs.
|
|
90
|
+
3. Content-addressed, SHA-256 verified chunked HTTP Range artifact caching.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "sharedots"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Universal Distributed Compute Network — Python SDK & Remote Execution"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [{ name = "Sharedots Team" }]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Programming Language :: Python :: 3",
|
|
15
|
+
"Topic :: System :: Distributed Computing",
|
|
16
|
+
]
|
|
17
|
+
dependencies = []
|
|
18
|
+
|
|
19
|
+
[project.optional-dependencies]
|
|
20
|
+
dev = [
|
|
21
|
+
"cloudpickle>=3.0.0",
|
|
22
|
+
"numpy>=1.24.0",
|
|
23
|
+
"pytest>=7.0.0",
|
|
24
|
+
"pytest-xdist>=3.5.0",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[tool.pytest.ini_options]
|
|
28
|
+
testpaths = ["tests"]
|
|
29
|
+
pythonpath = ["."]
|
|
30
|
+
addopts = "--import-mode=importlib -ra -q"
|
|
31
|
+
|
|
32
|
+
[project.scripts]
|
|
33
|
+
sharedots-runner = "sharedots.runner:main"
|
sharedots-0.1.0/setup.py
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""Sharedots Python SDK — Universal Distributed Compute & Remote Execution."""
|
|
2
|
+
|
|
3
|
+
from .client import Client, connect
|
|
4
|
+
from .exceptions import (
|
|
5
|
+
ArtifactError,
|
|
6
|
+
AuthenticationError,
|
|
7
|
+
JobTimeoutError,
|
|
8
|
+
RemoteExecutionError,
|
|
9
|
+
SharedotsError,
|
|
10
|
+
)
|
|
11
|
+
from .future import SharedotsFuture, gather
|
|
12
|
+
from .remote import RemoteFunction, remote
|
|
13
|
+
from .room import Room
|
|
14
|
+
|
|
15
|
+
__version__ = "0.1.0"
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"Client",
|
|
19
|
+
"connect",
|
|
20
|
+
"Room",
|
|
21
|
+
"remote",
|
|
22
|
+
"RemoteFunction",
|
|
23
|
+
"SharedotsFuture",
|
|
24
|
+
"gather",
|
|
25
|
+
"SharedotsError",
|
|
26
|
+
"RemoteExecutionError",
|
|
27
|
+
"AuthenticationError",
|
|
28
|
+
"JobTimeoutError",
|
|
29
|
+
"ArtifactError",
|
|
30
|
+
]
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
"""Top-level Sharedots Client for managing rooms and remote compute decorators."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from typing import Any, Callable, Dict, Optional, Union
|
|
5
|
+
import urllib.error
|
|
6
|
+
import urllib.parse
|
|
7
|
+
import urllib.request
|
|
8
|
+
|
|
9
|
+
from .exceptions import AuthenticationError, SharedotsError
|
|
10
|
+
from .remote import RemoteFunction
|
|
11
|
+
from .room import Room
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class Client:
|
|
15
|
+
"""Entry point for connecting to a Sharedots coordinator cluster."""
|
|
16
|
+
|
|
17
|
+
def __init__(
|
|
18
|
+
self,
|
|
19
|
+
coordinator: str = "http://127.0.0.1:4000",
|
|
20
|
+
room_id: Optional[str] = None,
|
|
21
|
+
token: Optional[str] = None,
|
|
22
|
+
):
|
|
23
|
+
self.coordinator_url = coordinator.rstrip("/")
|
|
24
|
+
self.token = token
|
|
25
|
+
self.active_room: Optional[Room] = None
|
|
26
|
+
|
|
27
|
+
if room_id and token:
|
|
28
|
+
self.active_room = Room(self.coordinator_url, room_id, token)
|
|
29
|
+
|
|
30
|
+
def _check_render_notice(self, reason: Any) -> str:
|
|
31
|
+
if "onrender.com" in self.coordinator_url:
|
|
32
|
+
return (
|
|
33
|
+
f"\n💡 [Render Free Tier Notice] The coordinator at {self.coordinator_url} appears to be sleeping.\n"
|
|
34
|
+
" Render's free tier spins down after 15 min of inactivity. Please give it ~30-50 seconds to wake up and retry!"
|
|
35
|
+
)
|
|
36
|
+
return ""
|
|
37
|
+
|
|
38
|
+
def health(self) -> Dict[str, Any]:
|
|
39
|
+
"""Queries coordinator health status and protocol version."""
|
|
40
|
+
url = f"{self.coordinator_url}/api/health"
|
|
41
|
+
req = urllib.request.Request(url, method="GET")
|
|
42
|
+
try:
|
|
43
|
+
with urllib.request.urlopen(req) as resp:
|
|
44
|
+
return json.loads(resp.read().decode("utf-8"))
|
|
45
|
+
except urllib.error.URLError as e:
|
|
46
|
+
notice = self._check_render_notice(e.reason)
|
|
47
|
+
raise SharedotsError(f"Failed to reach coordinator at {self.coordinator_url}: {e.reason}{notice}")
|
|
48
|
+
|
|
49
|
+
def overview(self) -> Dict[str, Any]:
|
|
50
|
+
"""Queries overall cluster telemetry (total workers, cores, memory)."""
|
|
51
|
+
url = f"{self.coordinator_url}/api/overview"
|
|
52
|
+
req = urllib.request.Request(url, method="GET")
|
|
53
|
+
try:
|
|
54
|
+
with urllib.request.urlopen(req) as resp:
|
|
55
|
+
return json.loads(resp.read().decode("utf-8"))
|
|
56
|
+
except urllib.error.URLError as e:
|
|
57
|
+
notice = self._check_render_notice(e.reason)
|
|
58
|
+
raise SharedotsError(f"Failed to reach coordinator at {self.coordinator_url}: {e.reason}{notice}")
|
|
59
|
+
|
|
60
|
+
def create_room(self, name: Optional[str] = None) -> Room:
|
|
61
|
+
"""Creates a new authenticated room on the coordinator."""
|
|
62
|
+
url = f"{self.coordinator_url}/api/rooms"
|
|
63
|
+
payload = json.dumps({"name": name or "mesh-room"}).encode("utf-8")
|
|
64
|
+
headers = {"content-type": "application/json"}
|
|
65
|
+
req = urllib.request.Request(url, data=payload, headers=headers, method="POST")
|
|
66
|
+
|
|
67
|
+
try:
|
|
68
|
+
with urllib.request.urlopen(req) as resp:
|
|
69
|
+
data = json.loads(resp.read().decode("utf-8"))
|
|
70
|
+
except urllib.error.URLError as e:
|
|
71
|
+
raise SharedotsError(f"Failed to reach coordinator at {self.coordinator_url}: {e.reason}")
|
|
72
|
+
|
|
73
|
+
room = Room(
|
|
74
|
+
coordinator_url=self.coordinator_url,
|
|
75
|
+
room_id=data["roomId"],
|
|
76
|
+
token=data["secret"],
|
|
77
|
+
)
|
|
78
|
+
self.active_room = room
|
|
79
|
+
if not self.token:
|
|
80
|
+
self.token = data["secret"]
|
|
81
|
+
return room
|
|
82
|
+
|
|
83
|
+
def connect(self, room_id: str, token: Optional[str] = None) -> Room:
|
|
84
|
+
"""Connects to an existing room using its room ID and authentication token."""
|
|
85
|
+
effective_token = token or self.token
|
|
86
|
+
if not effective_token:
|
|
87
|
+
raise AuthenticationError("A room token (secret) is required to connect to a room")
|
|
88
|
+
|
|
89
|
+
# Verify room exists on coordinator
|
|
90
|
+
url = f"{self.coordinator_url}/api/rooms/{urllib.parse.quote(room_id)}"
|
|
91
|
+
try:
|
|
92
|
+
req = urllib.request.Request(url, method="GET")
|
|
93
|
+
with urllib.request.urlopen(req) as resp:
|
|
94
|
+
if resp.status != 200:
|
|
95
|
+
raise SharedotsError(f"Room {room_id} not found on coordinator")
|
|
96
|
+
except urllib.error.HTTPError as e:
|
|
97
|
+
if e.code == 404:
|
|
98
|
+
raise SharedotsError(f"Room {room_id} not found on coordinator")
|
|
99
|
+
raise
|
|
100
|
+
|
|
101
|
+
room = Room(self.coordinator_url, room_id, effective_token)
|
|
102
|
+
self.active_room = room
|
|
103
|
+
return room
|
|
104
|
+
|
|
105
|
+
def remote(
|
|
106
|
+
self,
|
|
107
|
+
fn: Optional[Callable[..., Any]] = None,
|
|
108
|
+
*,
|
|
109
|
+
cpu: float = 1.0,
|
|
110
|
+
memory: str = "512MB",
|
|
111
|
+
gpu: bool = False,
|
|
112
|
+
timeout_sec: int = 600,
|
|
113
|
+
max_attempts: int = 3,
|
|
114
|
+
name: Optional[str] = None,
|
|
115
|
+
) -> Union[RemoteFunction, Callable[[Callable[..., Any]], RemoteFunction]]:
|
|
116
|
+
"""Decorator binding a function to this Client's active room for distributed execution.
|
|
117
|
+
|
|
118
|
+
Usage:
|
|
119
|
+
client = sd.Client(coordinator="...", room_id="...", token="...")
|
|
120
|
+
|
|
121
|
+
@client.remote(cpu=2, memory="1GB", gpu=True)
|
|
122
|
+
def process_tensor(data):
|
|
123
|
+
return data * 2
|
|
124
|
+
|
|
125
|
+
future = process_tensor(my_data)
|
|
126
|
+
result = future.result()
|
|
127
|
+
"""
|
|
128
|
+
def decorator(target_fn: Callable[..., Any]) -> RemoteFunction:
|
|
129
|
+
if not self.active_room:
|
|
130
|
+
raise SharedotsError(
|
|
131
|
+
"No active room connected. Call client.create_room() or client.connect(...) first."
|
|
132
|
+
)
|
|
133
|
+
return RemoteFunction(
|
|
134
|
+
fn=target_fn,
|
|
135
|
+
room=self.active_room,
|
|
136
|
+
cpu=cpu,
|
|
137
|
+
memory=memory,
|
|
138
|
+
gpu=gpu,
|
|
139
|
+
timeout_sec=timeout_sec,
|
|
140
|
+
max_attempts=max_attempts,
|
|
141
|
+
name=name,
|
|
142
|
+
)
|
|
143
|
+
|
|
144
|
+
if fn is not None:
|
|
145
|
+
return decorator(fn)
|
|
146
|
+
return decorator
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def connect(
|
|
150
|
+
room: str,
|
|
151
|
+
token: str,
|
|
152
|
+
coordinator: str = "http://127.0.0.1:4000",
|
|
153
|
+
) -> Client:
|
|
154
|
+
"""Connects directly to an existing room and returns an authenticated Client instance."""
|
|
155
|
+
return Client(coordinator=coordinator, room_id=room, token=token)
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""Cryptographic and HMAC authentication utilities matching @sharedots/protocol."""
|
|
2
|
+
|
|
3
|
+
import hashlib
|
|
4
|
+
import hmac
|
|
5
|
+
import time
|
|
6
|
+
from typing import Dict, Union
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def compute_request_signature(
|
|
10
|
+
room_secret: str,
|
|
11
|
+
method: str,
|
|
12
|
+
path: str,
|
|
13
|
+
timestamp_sec: Union[int, str],
|
|
14
|
+
room_id: str,
|
|
15
|
+
) -> str:
|
|
16
|
+
"""Computes HMAC-SHA256 signature for authenticating HTTP requests to Coordinator."""
|
|
17
|
+
canonical = f"{method.upper()}\n{path}\n{str(timestamp_sec)}\n{room_id}"
|
|
18
|
+
return hmac.new(
|
|
19
|
+
room_secret.encode("utf-8"),
|
|
20
|
+
canonical.encode("utf-8"),
|
|
21
|
+
hashlib.sha256,
|
|
22
|
+
).hexdigest()
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def auth_headers(
|
|
26
|
+
room_secret: str,
|
|
27
|
+
room_id: str,
|
|
28
|
+
method: str,
|
|
29
|
+
path: str,
|
|
30
|
+
timestamp_sec: Union[int, None] = None,
|
|
31
|
+
) -> Dict[str, str]:
|
|
32
|
+
"""Generates standard Sharedots room authentication HTTP headers."""
|
|
33
|
+
ts = timestamp_sec if timestamp_sec is not None else int(time.time())
|
|
34
|
+
sig = compute_request_signature(room_secret, method, path, ts, room_id)
|
|
35
|
+
return {
|
|
36
|
+
"x-sharedots-room": room_id,
|
|
37
|
+
"x-sharedots-ts": str(ts),
|
|
38
|
+
"x-sharedots-sig": sig,
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def sha256_bytes(data: bytes) -> str:
|
|
43
|
+
"""Computes hexadecimal SHA-256 digest of binary payload."""
|
|
44
|
+
return hashlib.sha256(data).hexdigest()
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""Sharedots Python SDK Exceptions."""
|
|
2
|
+
|
|
3
|
+
from typing import Optional
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class SharedotsError(Exception):
|
|
7
|
+
"""Base exception for all Sharedots errors."""
|
|
8
|
+
pass
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class AuthenticationError(SharedotsError):
|
|
12
|
+
"""Raised when authentication with the Coordinator fails."""
|
|
13
|
+
pass
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class ArtifactError(SharedotsError):
|
|
17
|
+
"""Raised when artifact upload, download, or verification fails."""
|
|
18
|
+
pass
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class JobTimeoutError(SharedotsError):
|
|
22
|
+
"""Raised when waiting for a job or task times out."""
|
|
23
|
+
pass
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class RemoteExecutionError(SharedotsError):
|
|
27
|
+
"""Raised when a remote worker task raises an unhandled exception.
|
|
28
|
+
|
|
29
|
+
Attributes:
|
|
30
|
+
error_type: Name of the remote exception class.
|
|
31
|
+
error_message: String message of the exception.
|
|
32
|
+
remote_traceback: Full traceback captured on the remote worker node.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
def __init__(
|
|
36
|
+
self,
|
|
37
|
+
error_message: str,
|
|
38
|
+
error_type: Optional[str] = None,
|
|
39
|
+
remote_traceback: Optional[str] = None,
|
|
40
|
+
):
|
|
41
|
+
self.error_type = error_type or "Exception"
|
|
42
|
+
self.error_message = error_message
|
|
43
|
+
self.remote_traceback = remote_traceback
|
|
44
|
+
|
|
45
|
+
formatted = f"Remote task failed with {self.error_type}: {self.error_message}"
|
|
46
|
+
if self.remote_traceback:
|
|
47
|
+
formatted += f"\n--- Remote Worker Traceback ---\n{self.remote_traceback}"
|
|
48
|
+
super().__init__(formatted)
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
"""Future and asynchronous completion abstractions for Sharedots remote executions."""
|
|
2
|
+
|
|
3
|
+
import time
|
|
4
|
+
from typing import Any, List, Optional
|
|
5
|
+
|
|
6
|
+
try:
|
|
7
|
+
import cloudpickle as serializer
|
|
8
|
+
except ImportError:
|
|
9
|
+
import pickle as serializer
|
|
10
|
+
|
|
11
|
+
from .exceptions import JobTimeoutError, RemoteExecutionError, SharedotsError
|
|
12
|
+
from .room import Room
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class SharedotsFuture:
|
|
16
|
+
"""A Future representing the eventual result of a distributed compute task."""
|
|
17
|
+
|
|
18
|
+
def __init__(
|
|
19
|
+
self,
|
|
20
|
+
room: Room,
|
|
21
|
+
job_id: str,
|
|
22
|
+
task_index: int = 0,
|
|
23
|
+
task_id: Optional[str] = None,
|
|
24
|
+
):
|
|
25
|
+
self.room = room
|
|
26
|
+
self.job_id = job_id
|
|
27
|
+
self.task_index = task_index
|
|
28
|
+
self.task_id = task_id
|
|
29
|
+
self._cached_result: Optional[Any] = None
|
|
30
|
+
self._is_resolved = False
|
|
31
|
+
self._last_snapshot: Optional[dict] = None
|
|
32
|
+
|
|
33
|
+
def done(self) -> bool:
|
|
34
|
+
"""Returns True if the remote task has completed, failed, or was cancelled."""
|
|
35
|
+
if self._is_resolved:
|
|
36
|
+
return True
|
|
37
|
+
detail = self.room.get_job(self.job_id)
|
|
38
|
+
self._last_snapshot = detail
|
|
39
|
+
status = detail.get("status")
|
|
40
|
+
return status in ("completed", "failed", "cancelled")
|
|
41
|
+
|
|
42
|
+
@property
|
|
43
|
+
def status(self) -> str:
|
|
44
|
+
"""Returns the current execution status (queued, running, completed, failed, cancelled)."""
|
|
45
|
+
if self._is_resolved:
|
|
46
|
+
return "completed"
|
|
47
|
+
if not self._last_snapshot:
|
|
48
|
+
self._last_snapshot = self.room.get_job(self.job_id)
|
|
49
|
+
return self._last_snapshot.get("status", "unknown")
|
|
50
|
+
|
|
51
|
+
@property
|
|
52
|
+
def progress(self) -> float:
|
|
53
|
+
"""Returns execution progress percentage (0.0 to 100.0)."""
|
|
54
|
+
if self._is_resolved:
|
|
55
|
+
return 100.0
|
|
56
|
+
if not self._last_snapshot:
|
|
57
|
+
self._last_snapshot = self.room.get_job(self.job_id)
|
|
58
|
+
prog = self._last_snapshot.get("progress", {})
|
|
59
|
+
return float(prog.get("percent", 0.0))
|
|
60
|
+
|
|
61
|
+
def result(self, timeout: Optional[float] = None, poll_interval: float = 0.2) -> Any:
|
|
62
|
+
"""Waits for task completion and returns the unpickled result.
|
|
63
|
+
|
|
64
|
+
Raises:
|
|
65
|
+
JobTimeoutError: If the task exceeds timeout seconds.
|
|
66
|
+
RemoteExecutionError: If the remote task raised an exception on the worker.
|
|
67
|
+
SharedotsError: If the job was cancelled or encountered a system fault.
|
|
68
|
+
"""
|
|
69
|
+
if self._is_resolved:
|
|
70
|
+
return self._cached_result
|
|
71
|
+
|
|
72
|
+
start_time = time.time()
|
|
73
|
+
while True:
|
|
74
|
+
detail = self.room.get_job(self.job_id)
|
|
75
|
+
self._last_snapshot = detail
|
|
76
|
+
status = detail.get("status")
|
|
77
|
+
|
|
78
|
+
if status == "completed":
|
|
79
|
+
break
|
|
80
|
+
elif status == "failed":
|
|
81
|
+
err_msg = detail.get("errorMessage") or "Job execution failed"
|
|
82
|
+
err_code = detail.get("errorCode") or "EXECUTION_FAILED"
|
|
83
|
+
raise RemoteExecutionError(f"{err_code}: {err_msg}")
|
|
84
|
+
elif status == "cancelled":
|
|
85
|
+
raise SharedotsError(f"Job {self.job_id} was cancelled")
|
|
86
|
+
|
|
87
|
+
if timeout is not None and (time.time() - start_time) > timeout:
|
|
88
|
+
raise JobTimeoutError(f"Job {self.job_id} timed out after {timeout} seconds")
|
|
89
|
+
|
|
90
|
+
time.sleep(poll_interval)
|
|
91
|
+
|
|
92
|
+
# Job completed — resolve the specific task output artifact
|
|
93
|
+
tasks = detail.get("tasks", [])
|
|
94
|
+
output_artifact_id = None
|
|
95
|
+
|
|
96
|
+
task_info = None
|
|
97
|
+
if self.task_id:
|
|
98
|
+
task_info = next((t for t in tasks if t.get("taskId") == self.task_id), None)
|
|
99
|
+
if not task_info:
|
|
100
|
+
task_info = next((t for t in tasks if t.get("taskIndex") == self.task_index), None)
|
|
101
|
+
if not task_info and self.task_index < len(tasks):
|
|
102
|
+
task_info = tasks[self.task_index]
|
|
103
|
+
|
|
104
|
+
if task_info:
|
|
105
|
+
out = task_info.get("output")
|
|
106
|
+
if out and isinstance(out, dict):
|
|
107
|
+
output_artifact_id = out.get("artifactId")
|
|
108
|
+
|
|
109
|
+
# Fallback to result artifact if tasks list output was empty
|
|
110
|
+
if not output_artifact_id:
|
|
111
|
+
res_obj = detail.get("result") or {}
|
|
112
|
+
output_artifact_id = res_obj.get("resultArtifactId")
|
|
113
|
+
|
|
114
|
+
if not output_artifact_id:
|
|
115
|
+
raise SharedotsError(f"Job {self.job_id} task {self.task_index} completed without an output artifact")
|
|
116
|
+
|
|
117
|
+
# Download artifact and unpickle
|
|
118
|
+
artifact_bytes = self.room.download_artifact(output_artifact_id)
|
|
119
|
+
out_data = serializer.loads(artifact_bytes)
|
|
120
|
+
|
|
121
|
+
if not isinstance(out_data, dict) or "success" not in out_data:
|
|
122
|
+
# Direct raw return
|
|
123
|
+
self._cached_result = out_data
|
|
124
|
+
self._is_resolved = True
|
|
125
|
+
return out_data
|
|
126
|
+
|
|
127
|
+
if not out_data.get("success"):
|
|
128
|
+
err = out_data.get("error") or {}
|
|
129
|
+
raise RemoteExecutionError(
|
|
130
|
+
error_message=err.get("message", "Remote task execution failed"),
|
|
131
|
+
error_type=err.get("type"),
|
|
132
|
+
remote_traceback=err.get("traceback"),
|
|
133
|
+
)
|
|
134
|
+
|
|
135
|
+
self._cached_result = out_data.get("result")
|
|
136
|
+
self._is_resolved = True
|
|
137
|
+
return self._cached_result
|
|
138
|
+
|
|
139
|
+
def cancel(self, reason: str = "Cancelled by client") -> dict:
|
|
140
|
+
"""Cancels this job on the coordinator."""
|
|
141
|
+
return self.room.cancel_job(self.job_id, reason=reason)
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def gather(futures: List[SharedotsFuture], timeout: Optional[float] = None) -> List[Any]:
|
|
145
|
+
"""Waits for a list of SharedotsFutures and returns their results in order."""
|
|
146
|
+
start_time = time.time()
|
|
147
|
+
results = []
|
|
148
|
+
for f in futures:
|
|
149
|
+
remaining_timeout = None
|
|
150
|
+
if timeout is not None:
|
|
151
|
+
elapsed = time.time() - start_time
|
|
152
|
+
if elapsed >= timeout:
|
|
153
|
+
raise JobTimeoutError(f"gather() timed out after {timeout} seconds")
|
|
154
|
+
remaining_timeout = timeout - elapsed
|
|
155
|
+
results.append(f.result(timeout=remaining_timeout))
|
|
156
|
+
return results
|