opengris-scaler 1.12.28__cp313-cp313-musllinux_1_2_x86_64.whl

scaler/protocol/capnp/message.capnp

@@ -0,0 +1,218 @@
+@0xaf44f44ea94a4675;
+
+using CommonType = import "common.capnp";
+using Status = import "status.capnp";
+
+struct Task {
+    taskId @0 :Data;
+    source @1 :Data;
+    metadata @2 :Data;
+    funcObjectId @3 :Data;
+    functionArgs @4 :List(Argument);
+    capabilities @5 :List(CommonType.TaskCapability);
+
+    struct Argument {
+        type @0 :ArgumentType;
+        data @1 :Data;
+
+        enum ArgumentType {
+            task @0;
+            objectID @1;
+        }
+    }
+}
+
+struct TaskCancel {
+    struct TaskCancelFlags {
+        force @0 :Bool;
+    }
+
+    taskId @0 :Data;
+    flags @1 :TaskCancelFlags;
+}
+
+struct TaskLog {
+    taskId @0 :Data;
+    logType @1 :LogType;
+    content @2 :Text;
+
+    enum LogType {
+        stdout @0;
+        stderr @1;
+    }
+}
+
+struct TaskResult {
+    taskId @0 :Data;
+    resultType @1 :CommonType.TaskResultType;
+    metadata @2 :Data;
+    results @3 :List(Data);
+}
+
+struct TaskCancelConfirm {
+    taskId @0 :Data;
+    cancelConfirmType @1 :CommonType.TaskCancelConfirmType;
+}
+
+struct GraphTask {
+    taskId @0 :Data;
+    source @1 :Data;
+    targets @2 :List(Data);
+    graph @3 :List(Task);
+}
+
+struct ClientHeartbeat {
+    resource @0 :Status.Resource;
+    latencyUS @1 :UInt32;
+}
+
+struct ClientHeartbeatEcho {
+    objectStorageAddress @0 :CommonType.ObjectStorageAddress;
+}
+
+struct WorkerHeartbeat {
+    agent @0 :Status.Resource;
+    rssFree @1 :UInt64;
+    queueSize @2 :UInt32;
+    queuedTasks @3 :UInt32;
+    latencyUS @4 :UInt32;
+    taskLock @5 :Bool;
+    processors @6 :List(Status.ProcessorStatus);
+    capabilities @7 :List(CommonType.TaskCapability);
+}
+
+struct WorkerHeartbeatEcho {
+    objectStorageAddress @0 :CommonType.ObjectStorageAddress;
+}
+
+struct ObjectInstruction {
+    instructionType @0 :ObjectInstructionType;
+    objectUser @1 :Data;
+    objectMetadata @2 :CommonType.ObjectMetadata;
+
+    enum ObjectInstructionType {
+        create @0;
+        delete @1;
+        clear @2;
+    }
+}
+
+struct DisconnectRequest {
+    worker @0 :Data;
+}
+
+struct DisconnectResponse {
+    worker @0 :Data;
+}
+
+struct ClientDisconnect {
+    disconnectType @0 :DisconnectType;
+
+    enum DisconnectType {
+        disconnect @0;
+        shutdown @1;
+    }
+}
+
+struct ClientShutdownResponse {
+    accepted @0 :Bool;
+}
+
+struct StateClient {
+}
+
+struct StateObject {
+}
+
+struct StateBalanceAdvice {
+    workerId @0 :Data;
+    taskIds @1 :List(Data);
+}
+
+struct StateScheduler {
+    binder @0 :Status.BinderStatus;
+    scheduler @1 :Status.Resource;
+    rssFree @2 :UInt64;
+    clientManager @3 :Status.ClientManagerStatus;
+    objectManager @4 :Status.ObjectManagerStatus;
+    taskManager @5 :Status.TaskManagerStatus;
+    workerManager @6 :Status.WorkerManagerStatus;
+    scalingManager @7 :Status.ScalingManagerStatus;
+}
+
+struct StateWorker {
+    workerId @0 :Data;
+    state@1 :CommonType.WorkerState;
+    capabilities @2 :List(CommonType.TaskCapability);
+}
+
+struct StateTask {
+    taskId @0 :Data;
+    functionName @1 :Data;
+    state @2 :CommonType.TaskState;
+    worker @3 :Data;
+    capabilities @4 :List(CommonType.TaskCapability);
+    metadata @5 :Data;
+}
+
+struct StateGraphTask {
+    enum NodeTaskType {
+        normal @0;
+        target @1;
+    }
+
+    graphTaskId @0 :Data;
+    taskId @1 :Data;
+    nodeTaskType @2 :NodeTaskType;
+    parentTaskIds @3 :List(Data);
+}
+
+struct ProcessorInitialized {
+}
+
+struct InformationRequest {
+    request @0 :Data;
+}
+
+struct InformationResponse {
+    response @0 :Data;
+}
+
+struct Message {
+    union {
+        task @0 :Task;
+        taskCancel @1 :TaskCancel;
+        taskCancelConfirm @2 :TaskCancelConfirm;
+        taskResult @3 :TaskResult;
+        taskLog @4 :TaskLog;
+
+        graphTask @5 :GraphTask;
+
+        objectInstruction @6 :ObjectInstruction;
+
+        clientHeartbeat @7 :ClientHeartbeat;
+        clientHeartbeatEcho @8 :ClientHeartbeatEcho;
+
+        workerHeartbeat @9 :WorkerHeartbeat;
+        workerHeartbeatEcho @10 :WorkerHeartbeatEcho;
+
+        disconnectRequest @11 :DisconnectRequest;
+        disconnectResponse @12 :DisconnectResponse;
+
+        stateClient @13 :StateClient;
+        stateObject @14 :StateObject;
+        stateBalanceAdvice @15 :StateBalanceAdvice;
+        stateScheduler @16 :StateScheduler;
+        stateWorker @17 :StateWorker;
+        stateTask @18 :StateTask;
+        stateGraphTask @19 :StateGraphTask;
+
+        clientDisconnect @20 :ClientDisconnect;
+        clientShutdownResponse @21 :ClientShutdownResponse;
+
+        processorInitialized @22 :ProcessorInitialized;
+
+        informationRequest @23 :InformationRequest;
+        informationResponse @24 :InformationResponse;
+    }
+}

scaler/protocol/capnp/object_storage.capnp

@@ -0,0 +1,57 @@
+@0xc2a14174aa42a12a;
+
+using Cxx = import "/capnp/c++.capnp";
+$Cxx.namespace("scaler::protocol");
+
+struct ObjectRequestHeader {
+    objectID @0: ObjectID; # 32 bytes
+    payloadLength @1: UInt64; # 8 bytes
+    requestID @2: UInt64; # 8 bytes
+    requestType @3: ObjectRequestType; # 2 bytes
+
+    enum ObjectRequestType {
+        # Set or override an object to the message's payload.
+        # Overrides the object's content if it already exists
+        # Always immediately answers with a setOK message.
+        setObject @0;
+
+        # Get an object's content.
+        # If the object does not exist, delays the getOk response until the object is created.
+        getObject @1;
+
+        # Remove the object.
+        deleteObject @2;
+
+        # Creates the provided object ID by linking it to the content of the object ID provided in payload.
+        # Overrides the object content if the new object ID already exists.
+        # If the referenced object does not exist, delays the duplicateOK response until the original object is created.
+        duplicateObjectID @3;
+
+        # Request the server to give back internal information, result is returned as payload.
+        # schema: three uint64_t tuple (number of ids, number of objects (hashes), total actual object size in bytes)
+        infoGetTotal @4;
+    }
+}
+
+struct ObjectID {
+    field0 @0: UInt64;
+    field1 @1: UInt64;
+    field2 @2: UInt64;
+    field3 @3: UInt64;
+}
+
+struct ObjectResponseHeader {
+    objectID @0: ObjectID;
+    payloadLength @1: UInt64;
+    responseID @2: UInt64; # 8 bytes
+    responseType @3: ObjectResponseType;
+
+    enum ObjectResponseType {
+        setOK @0;
+        getOK @1;
+        delOK @2;
+        delNotExists @3;
+        duplicateOK @4;
+        infoGetTotalOK @5;
+    }
+}

scaler/protocol/capnp/status.capnp

@@ -0,0 +1,73 @@
+@0xa4dfa1212ad2d0f0;
+
+struct Resource {
+    cpu @0 :UInt16;   # 99.2% will be represented as 992 as integer
+    rss @1 :UInt64;  # 32bit is capped to 4GB, so use 64bit to represent
+}
+
+struct ObjectManagerStatus {
+    numberOfObjects @0 :UInt32;
+}
+
+struct ClientManagerStatus {
+    clientToNumOfTask @0 :List(Pair);
+
+    struct Pair {
+        client @0 :Data;
+        numTask @1 :UInt32;
+    }
+}
+
+struct TaskManagerStatus {
+    stateToCount @0 :List(Pair);
+
+    struct Pair {
+        state @0 :UInt8;
+        count @1 :UInt32;
+    }
+}
+
+struct ProcessorStatus {
+    pid @0 :UInt32;
+    initialized @1 :Bool;
+    hasTask @2 :Bool;
+    suspended @3 :Bool;
+    resource @4 :Resource;
+}
+
+struct WorkerStatus {
+    workerId @0 :Data;
+    agent @1 :Resource;
+    rssFree @2 :UInt64;
+    free @3 :UInt32;
+    sent @4 :UInt32;
+    queued @5 :UInt32;
+    suspended @6: UInt8;
+    lagUS @7 :UInt64;
+    lastS @8 :UInt8;
+    itl @9 :Text;
+    processorStatuses @10 :List(ProcessorStatus);
+}
+
+struct WorkerManagerStatus {
+    workers @0 :List(WorkerStatus);
+}
+
+struct ScalingManagerStatus {
+    workerGroups @0 :List(Pair);
+
+    struct Pair {
+        workerGroupID @0 :Data;
+        workerIDs @1 :List(Data);
+    }
+}
+
+struct BinderStatus {
+    received @0 :List(Pair);
+    sent @1 :List(Pair);
+
+    struct Pair {
+        client @0 :Text;
+        number @1 :UInt32;
+    }
+}

scaler/protocol/introduction.md

@@ -0,0 +1,105 @@
+# Roles
+
+The communication protocol include 3 roles: client, scheduler and worker:
+
+- client is upstream of scheduler, scheduler is upstream of worker
+- worker is downstream of scheduler, scheduler is downstream of client
+
+```plaintext
+                                                     +--------------+
+                      +-----------------+    TCP     |              |
+                      |                 +------------+    worker    |
++-----------+         |                 |            |              |
+|           |   TCP   |                 |            +--------------+
+|  client   +---------+                 |
+|           |         |                 |            +--------------+
++-----------+         |                 |    TCP     |              |
+                      |    scheduler    +------------+    worker    |
++-----------+         |  (object store) |            |              |
+|           |   TCP   |                 |            +--------------+
+|  client   +---------+                 |
+|           |         |                 |            +--------------+
++-----------+         |                 |    TCP     |              |
+                      |                 +------------+    worker    |
+                      +-----------------+            |              |
+                                                     +--------------+
+
+```
+
+each client to scheduler and each worker to scheduler only maintains 1 TCP connection
+
+# Message format
+
+Scaler is using capnp library to serialize/deserialize and use zmq to communicate between client and scheduler and
+worker
+
+# Message Type Category
+
+In general, there are 2 categories of the message types: object and task
+
+object normally has an object id associated with actual object data, object data is immutable bytes, serialized by
+client/worker, and deserialized by client/worker. protocol didn't define the way to serialize it, it's up to the
+client/worker to decide
+
+task is a function call, it has a task id associate with the actual function call, and the function call contains
+function and series of arguments, but task message doesn't contain the actual function and arguments, instead it
+contains object ids, workers are responsible to fetch the function/argument data from scheduler and deserialize and
+execute the function call.
+
+## Object Channel
+
+Scheduler is the center of the object storage, client and worker are identical and can push
+
+```plaintext
+                                                      ObjectInstruction
+                                                       ObjectResponse   +--------------+
+                                                    +------------------>|              |
+                                                    |                   |   Worker     |
++---------+                        +-----------+    |  +----------------+              |
+|         |     ObjectRequest      |           +----+  | ObjectRequest  +--------------+
+|         |   ObjectInstruction    |           |       |
+|         +----------------------->|           |<------+
+|  Client |                        | Scheduler |
+|         |<-----------------------+           +-------+
+|         |    ObjectResponse      |           |       | ObjectInstruction
+|         |                        |           +<---+  | ObjectResponse +--------------+
++---------+                        +-----------+    |  +--------------->|              |
+                                                    |                   |   Worker     |
+                                                    +-------------------+              |
+                                                         ObjectRequest  +--------------+
+
+```
+
+ObjectInstruction = b"OI"
+client can send object instruction to scheduler, scheduler can send object instruction to worker
+it has 2 subtypes: create b"C", delete b"D"
+when subtype is create, it has to include:
+
+- list of object id (type bytes)
+- list of object names (type bytes)
+- list of object bytes (type bytes)
+  All above 3 lists, the number of items need match
+
+ObjectRequest = b"OR"
+ObjectResponse = b"OA"
+
+## Task Channel
+
+```plaintext
+                                                             Task
+                                                          TaskCancel    +--------------+
+                                                    +-------------------+              |
+                                                    |                   |   Worker     |
++---------+         Task           +-----------+    |  +----------------+              |
+|         |      TaskCancel        |           +----+  |  TaskResult    +--------------+
+|         |      GraphTask         |           |       |
+|         +------------------------+           |<------+
+|  Client |                        | Scheduler |
+|         |<-----------------------+           +-------+
+|         |        TaskEcho        |           |       |     Task
+|         |       TaskResult       |           +----+  |  TaskCancel    +--------------+
++---------+                        +-----------+    |  +--------------->|              |
+                                                    |                   |   Worker     |
+                                                    +-------------------+              |
+                                                          TaskResult    +--------------+
+```

scaler/protocol/python/common.py

@@ -0,0 +1,140 @@
+import dataclasses
+import enum
+from typing import Tuple
+
+from scaler.protocol.capnp._python import _common  # noqa
+from scaler.protocol.python.mixins import Message
+from scaler.utility.identifiers import ObjectID
+
+
+class TaskResultType(enum.Enum):
+    Success = _common.TaskResultType.success  # if submit and task is done and get result
+    Failed = _common.TaskResultType.failed  # if submit and task is failed on worker
+    FailedWorkerDied = _common.TaskResultType.failedWorkerDied  # if submit and worker died
+
+
+class TaskCancelConfirmType(enum.Enum):
+    Canceled = _common.TaskCancelConfirmType.canceled  # if cancel success
+    CancelFailed = _common.TaskCancelConfirmType.cancelFailed  # if failed to cancel if task is running
+    CancelNotFound = _common.TaskCancelConfirmType.cancelNotFound  # if try to cancel, and task is not found
+
+
+class TaskTransition(enum.Enum):
+    HasCapacity = _common.TaskTransition.hasCapacity
+    TaskResultSuccess = _common.TaskTransition.taskResultSuccess
+    TaskResultFailed = _common.TaskTransition.taskResultFailed
+    TaskResultWorkerDied = _common.TaskTransition.taskResultWorkerDied
+    TaskCancel = _common.TaskTransition.taskCancel
+    TaskCancelConfirmCanceled = _common.TaskTransition.taskCancelConfirmCanceled
+    TaskCancelConfirmFailed = _common.TaskTransition.taskCancelConfirmFailed
+    TaskCancelConfirmNotFound = _common.TaskTransition.taskCancelConfirmNotFound
+    BalanceTaskCancel = _common.TaskTransition.balanceTaskCancel
+    WorkerDisconnect = _common.TaskTransition.workerDisconnect
+    SchedulerHasTask = _common.TaskTransition.schedulerHasTask
+    SchedulerHasNoTask = _common.TaskTransition.schedulerHasNoTask
+
+
+class TaskState(enum.Enum):
+    Inactive = _common.TaskState.inactive  # task is scheduled but not allocate to worker
+    Running = _common.TaskState.running  # task is running in worker
+    Canceling = _common.TaskState.canceling  # task is canceling state
+    BalanceCanceling = _common.TaskState.balanceCanceling  # task is in balance canceling state
+    Success = _common.TaskState.success  # task is finished properly
+    Failed = _common.TaskState.failed  # task is finished but exception happened
+    FailedWorkerDied = _common.TaskState.failedWorkerDied  # task is failed due to worker died
+    Canceled = _common.TaskState.canceled  # task is canceled (received task cancel confirm)
+    CanceledNotFound = _common.TaskState.canceledNotFound  # task is not found when trying to cancel
+    WorkerDisconnecting = _common.TaskState.workerDisconnecting  # task is lost due to worker disconnecting
+
+
+class WorkerState(enum.Enum):
+    Connected = _common.WorkerState.connected
+    Disconnected = _common.WorkerState.disconnected
+
+
+@dataclasses.dataclass
+class TaskCapability(Message):
+    def __init__(self, msg):
+        super().__init__(msg)
+
+    @property
+    def name(self) -> str:
+        return self._msg.name
+
+    @property
+    def value(self) -> int:
+        return self._msg.value
+
+    @staticmethod
+    def new_msg(name: str, value: int) -> "TaskCapability":
+        return TaskCapability(_common.TaskCapability(name=name, value=value))
+
+    def get_message(self):
+        return self._msg
+
+
+@dataclasses.dataclass
+class ObjectMetadata(Message):
+    class ObjectContentType(enum.Enum):
+        # FIXME: Pycapnp does not support assignment of raw enum values when the enum is itself declared within a list.
+        # However, assigning the enum's string value works.
+        # See https://github.com/capnproto/pycapnp/issues/374
+
+        Serializer = "serializer"
+        Object = "object"
+
+    def __init__(self, msg):
+        super().__init__(msg)
+
+    @property
+    def object_ids(self) -> Tuple[ObjectID, ...]:
+        return tuple(ObjectID(object_id_bytes) for object_id_bytes in self._msg.objectIds)
+
+    @property
+    def object_types(self) -> Tuple[ObjectContentType, ...]:
+        return tuple(ObjectMetadata.ObjectContentType(object_type._as_str()) for object_type in self._msg.objectTypes)
+
+    @property
+    def object_names(self) -> Tuple[bytes, ...]:
+        return tuple(self._msg.objectNames)
+
+    @staticmethod
+    def new_msg(
+        object_ids: Tuple[ObjectID, ...],
+        object_types: Tuple[ObjectContentType, ...] = tuple(),
+        object_names: Tuple[bytes, ...] = tuple(),
+    ) -> "ObjectMetadata":
+        return ObjectMetadata(
+            _common.ObjectMetadata(
+                objectIds=[bytes(object_id) for object_id in object_ids],
+                objectTypes=[object_type.value for object_type in object_types],
+                objectNames=list(object_names),
+            )
+        )
+
+    def get_message(self):
+        return self._msg
+
+
+@dataclasses.dataclass
+class ObjectStorageAddress(Message):
+    def __init__(self, msg):
+        super().__init__(msg)
+
+    @property
+    def host(self) -> str:
+        return self._msg.host
+
+    @property
+    def port(self) -> int:
+        return self._msg.port
+
+    @staticmethod
+    def new_msg(host: str, port: int) -> "ObjectStorageAddress":
+        return ObjectStorageAddress(_common.ObjectStorageAddress(host=host, port=port))
+
+    def get_message(self):
+        return self._msg
+
+    def __repr__(self) -> str:
+        return f"tcp://{self.host}:{self.port}"