opengris-scaler 1.12.37__cp38-cp38-musllinux_1_2_x86_64.whl

scaler/config/config_class.py

@@ -0,0 +1,317 @@
+import dataclasses
+import typing
+from typing import Any, Dict, Type, TypeVar
+
+from configargparse import ArgParser, ArgumentDefaultsHelpFormatter, TomlConfigParser
+
+from scaler.config.mixins import ConfigType
+
+T = TypeVar("T", bound="ConfigClass")
+
+
+class ConfigClass:
+    """
+    An abstract interface for dataclasses where the fields define command line options,
+    config file options, and environment variables.
+
+    Subclasses of `ConfigClass` must be dataclasses.
+    Subclasses of `ConfigClass` are called "config classes".
+
+    ## Config Files
+
+    All options with a long name can be parsed from a TOML config file specified with `--config` or `-c`.
+    The section name is determined by the subclass' implementation of `.section_name()`.
+
+    ## Environment Variables
+
+    Any parameter can be configured to read from an environment variable by adding `env="NAME"` to the field metadata.
+
+    ```python
+    # can be set as --my-field on the command line or in a config file, or using the environment variable `NAME`
+    my_field: int = dataclasses.field(metadata=dict(env="NAME"))
+    ```
+
+    ## Precedence
+
+    When a parameter is supplied in multiple ways, the following precedence is observed:
+    command line > environment variables > config file > defaults
+
+    ## Customization
+
+    Any key values included in the field's metadata will be passed through to `.add_argument()`
+    and will always take precedence over derived values, except for `default`.
+
+    The value for `default` is taken from the field's default. Providing `default` in the field
+    metadata will result in a `TypeError`.
+
+    ```python
+    # passes through options
+    custom_field: int = dataclasses.field(
+        metadata=dict(
+            choices=["apples", "oranges"],
+            help="choose a fruit",
+        )
+    )
+
+    # TypeError!
+    bad: int = dataclasses.field(metadata=dict(default=0))
+    ```
+
+    ## Naming Fields
+
+    The name of the dataclass fields (replacing underscores with hyphens) is used
+    as the long option name for command line and config file parameters.
+    A short name for the argument can be provided in the field metadata using the `short` key.
+    The value is the short option name and must include the hyphen, e.g. `-n`.
+
+    There is one restriction: `--config` and `-c` are reserved for the config file.
+
+    ```python
+    # this will have long name --field-one, and no short name
+    field_one: int = 5
+
+    # sets a short name
+    field_two: int = dataclasses.field(default=5, metadata=dict(short="-f2"))
+    ```
+
+    ## Default Values
+
+    The default value of the field is also used as the default for the argument parser.
+
+    ```python
+    lang: str = "en"
+    name: str = dataclasses.field(default="Arthur")
+    ```
+
+    ## Positional Parameters
+
+    You can set `positional=True` in the metadata dict to make an argument positional.
+    In this case long and short names are ignored, use `name` to override the name of the option.
+    The position is dependent on field ordering.
+
+    ```python
+    # both of these are positional, and field one must be specified before field two
+    field_one: int = dataclasses.field(metadata=dict(positional=True))
+    field_two: int = dataclasses.field(metadata=dict(positional=True))
+    ```
+
+    ## Composition
+
+    Config classes can be composed. If a config class has fields that are config classes,
+    then the options of the child config class are inherited as if that child config class'
+    fields were added to the parent, for the purpose of parsing arguments. When the dataclass
+    is created, the structure is kept.
+
+    Care needs to be taken so that field names do not conflict with each other.
+    The name of fields in nested config classes are in the same namespace as those
+    in the parent and other nested config classes.
+
+    ## Parameter Types
+
+    The type of a field is used as the type in argument parsing, meaning that it must be able
+    to be directly constructed from a string.
+
+    Special handling is implemented for several common types:
+    - `bool`: parses from "true" and "false", and all upper/lower case variants
+    - subclasses of `ConfigType`: uses the `.from_string()` method
+    - `Optional[T]`, `T | None`: parsed as `T` and sets `required=False`
+    - `List[T]`, `list[T]`: parsed as `T`, and sets `nargs="*"`
+
+    For generic types, the `T` is parsed recursively following the rules here.
+    For example, `Optional[T]` where `T` is a subclass of `ConfigType`
+    will still use `T.from_string()`.
+
+    as usual, all of these can be overriden by setting the option in the metadata.
+
+    ```python
+    # this provides a custom `type` to parse the input as hexadecimal
+    # `type` must be a callable that accepts a string
+    # refer to the argparse docs for more
+    hex: int = dataclasses.field(metadata=dict(type=lambda s: int(s, 16)))
+
+    class MyConfigType(ConfigType):
+        ...
+
+    # this will work as expected
+    my_field: MyConfigType
+
+    # this requires special handling
+    tuples: Tuple[int, ...] = dataclasses.field(metadata=dict(type=int, nargs="*"))
+
+    # works automatically, defaults to `nargs="*"`
+    integers: List[int]
+
+    # ... but we can override that
+    integers2: List[int] = dataclasses.field(metadata=dict(nargs="+"))
+
+    # this will automatically have `required=False` set
+    maybe: Optional[str]
+    """
+
+    @classmethod
+    def configure_parser(cls: type, parser: ArgParser):
+        fields = dataclasses.fields(cls)
+
+        for field in fields:
+            if is_config_class(field.type):
+                field.type.configure_parser(parser)  # type: ignore[union-attr]
+                continue
+
+            kwargs = dict(field.metadata)
+
+            # usually command line options use hyphens instead of underscores
+
+            if kwargs.pop("positional", False):
+                args = [kwargs.pop("name", field.name)]
+            else:
+                long_name = kwargs.pop("long", f"--{field.name.replace('_', '-')}")
+                if "short" in kwargs:
+                    args = [long_name, kwargs.pop("short")]
+                else:
+                    args = [long_name]
+
+                # this sets the key given back when args are parsed
+                kwargs["dest"] = field.name
+
+            if "default" in kwargs:
+                raise TypeError("'default' cannot be provided in field metadata")
+
+            if field.default != dataclasses.MISSING:
+                kwargs["default"] = field.default
+
+            if field.default_factory != dataclasses.MISSING:
+                kwargs["default"] = field.default_factory()
+
+            # when store true or store false is set, setting the type raises a type error
+            if kwargs.get("action") not in ("store_true", "store_false"):
+
+                # sometimes the user will set the type manually
+                # this is required for types such as `Option[T]`, where they cannt be directly constructed from a string
+                if "type" not in kwargs:
+                    opts = get_type_args(field.type)
+
+                    # set all of the options, except where already set
+                    for key, value in opts.items():
+                        if key not in kwargs:
+                            kwargs[key] = value
+
+            parser.add_argument(*args, **kwargs)
+
+    @classmethod
+    def parse(cls: Type[T], program_name: str, section: str) -> T:
+        parser = ArgParser(
+            program_name,
+            formatter_class=ArgumentDefaultsHelpFormatter,
+            config_file_parser_class=TomlConfigParser(sections=[section]),
+        )
+
+        parser.add_argument("--config", "-c", is_config_file=True, help="Path to the TOML configuration file.")
+        cls.configure_parser(parser)
+
+        kwargs = vars(parser.parse_args())
+
+        # remove this from the args
+        kwargs.pop("config")
+
+        # we need to manually handle any ConfigClass fields
+        for field in dataclasses.fields(cls):  # type: ignore[arg-type]
+            if is_config_class(field.type):
+
+                # steal arguments for the config class
+                inner_kwargs = {}
+                for f in dataclasses.fields(field.type):  # type: ignore[arg-type]
+                    if f.name in kwargs:
+                        inner_kwargs[f.name] = kwargs.pop(f.name)
+
+                # instantiate and update the args
+                kwargs[field.name] = field.type(**inner_kwargs)  # type: ignore[operator]
+
+        return cls(**kwargs)
+
+
+def parse_bool(s: str) -> bool:
+    """parse a bool from a conventional string representation"""
+
+    lower = s.lower()
+    if lower == "true":
+        return True
+    if lower == "false":
+        return False
+
+    raise TypeError(f"[{s}] is not a valid bool")
+
+
+def is_optional(ty: Any) -> bool:
+    """determines if `ty` is typing.Optional"""
+    return typing.get_origin(ty) is typing.Union and typing.get_args(ty)[1] is type(None)
+
+
+def get_optional_type(ty: Any) -> type:
+    """get the `T` from a typing.Optional[T]"""
+    return typing.get_args(ty)[0]
+
+
+def is_list(ty: Any) -> bool:
+    """determines if `ty` is typing.List or list"""
+    return typing.get_origin(ty) is list or ty is list
+
+
+def get_list_type(ty: Any) -> type:
+    """get the generic type of a typing.List[T] or list[T]"""
+    return typing.get_args(ty)[0]
+
+
+def is_config_type(ty: Any) -> bool:
+    """determines if ty is a subclass of ConfigType"""
+    try:
+        return issubclass(ty, ConfigType)
+    except TypeError:
+        return False
+
+
+def is_config_class(ty: Any) -> bool:
+    """determines if ty is a subclass of ConfigClass"""
+    try:
+        return issubclass(ty, ConfigClass)
+    except TypeError:
+        return False
+
+
+def get_type_args(ty: Any) -> Dict[str, Any]:
+    """
+    The type of a field implies several options for its argument parsing,
+    such as `type`, `nargs`, and `required`
+
+    For example a parameter of type Option[T] is parsed as `T`,
+    has no implication on `nargs`, and is not required
+
+    Similarly a parameter of List[T] is also parsed as `T`,
+    might have `nargs="*"`, and has no implication on `required`
+
+    This function determines these settings based upon a given type.
+    """
+
+    # bools have special parsing so that they behave as users expect
+    if ty is bool:
+        return {"type": parse_bool}
+
+    # for subclasses of ConfigType, we use the .from_string() method
+    if is_config_type(ty):
+        return {"type": ty.from_string}
+
+    # recursing handles the case where e.g. the inner type is a bool
+    # or a subclass of ConfigType, both of which need special handling
+    #
+    # parameters with this type are optional so we set `required=False`
+    if is_optional(ty):
+        opts = get_type_args(get_optional_type(ty))
+        return {"type": opts["type"], "required": False}
+
+    # `nargs="*"` is a reasonable default for lists that be overriden by the user
+    # if other behaviour is desired
+    if is_list(ty):
+        opts = get_type_args(get_list_type(ty))
+        return {"type": opts["type"], "nargs": "*"}
+
+    # the default, just use the type as-is
+    return {"type": ty}

scaler/config/defaults.py

@@ -0,0 +1,94 @@
+import os
+
+from scaler.config.types.network_backend import NetworkBackend
+
+# ==============
+# SYSTEM OPTIONS
+
+# object clean up time interval
+CLEANUP_INTERVAL_SECONDS = 1
+
+# status report interval, used by poke or scaled monitor
+STATUS_REPORT_INTERVAL_SECONDS = 1
+
+# number of seconds for profiling
+PROFILING_INTERVAL_SECONDS = 1
+
+# cap'n proto only allow Data/Text/Blob size to be as big as 500MB
+CAPNP_DATA_SIZE_LIMIT = 2**29 - 1
+
+# message size limitation, max can be 2**64
+CAPNP_MESSAGE_SIZE_LIMIT = 2**64 - 1
+
+# ==========================
+# SCHEDULER SPECIFIC OPTIONS
+
+# number of threads for zmq socket to handle
+DEFAULT_IO_THREADS = 1
+
+# if all workers are full and busy working, this option determine how many additional tasks scheduler can receive and
+# queued, if additional number of tasks received exceeded this number, scheduler will reject tasks
+DEFAULT_MAX_NUMBER_OF_TASKS_WAITING = -1
+
+# if didn't receive heartbeat for following seconds, then scheduler will treat worker as dead and reschedule unfinished
+# tasks for this worker
+DEFAULT_WORKER_TIMEOUT_SECONDS = 60
+
+# if didn't receive heartbeat for following seconds, then scheduler will treat client as dead and cancel remaining
+# tasks for this client
+DEFAULT_CLIENT_TIMEOUT_SECONDS = 60
+
+# number of seconds for load balance, if value is -1 means disable load balance
+DEFAULT_LOAD_BALANCE_SECONDS = 1
+
+# when load balance advice happened repeatedly and always be the same, we issue load balance request when exact repeated
+# times happened
+DEFAULT_LOAD_BALANCE_TRIGGER_TIMES = 2
+
+# number of tasks can be queued to each worker on scheduler side
+DEFAULT_PER_WORKER_QUEUE_SIZE = 1000
+
+# =======================
+# WORKER SPECIFIC OPTIONS
+
+# number of workers, echo worker use 1 process
+DEFAULT_NUMBER_OF_WORKER = os.cpu_count() - 1
+
+# number of seconds that worker agent send heartbeat to scheduler
+DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 2
+
+# number of seconds the object cache kept in worker's memory
+DEFAULT_OBJECT_RETENTION_SECONDS = 60
+
+# number of seconds worker doing garbage collection
+DEFAULT_GARBAGE_COLLECT_INTERVAL_SECONDS = 30
+
+# number of bytes threshold for worker process that trigger deep garbage collection
+DEFAULT_TRIM_MEMORY_THRESHOLD_BYTES = 1024 * 1024 * 1024
+
+# default task timeout seconds, 0 means never timeout
+DEFAULT_TASK_TIMEOUT_SECONDS = 0
+
+# number of seconds that worker agent wait for processor to finish before killing it
+DEFAULT_PROCESSOR_KILL_DELAY_SECONDS = 3
+
+# number of seconds without scheduler contact before worker shuts down
+DEFAULT_WORKER_DEATH_TIMEOUT = 5 * 60
+
+# if true, suspended worker's processors will be actively suspended with a SIGTSTP signal, otherwise a synchronization
+# event will be used.
+DEFAULT_HARD_PROCESSOR_SUSPEND = False
+
+# =======================
+# LOGGING SPECIFIC OPTIONS
+
+# default logging level
+DEFAULT_LOGGING_LEVEL = "INFO"
+
+# default logging paths
+DEFAULT_LOGGING_PATHS = ("/dev/stdout",)
+
+# =======================
+# SCALER NETWORK BACKEND SPECIFIC OPTIONS
+
+SCALER_NETWORK_BACKEND = NetworkBackend.tcp_zmq

scaler/config/mixins.py

@@ -0,0 +1,20 @@
+import abc
+import sys
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+
+class ConfigType(metaclass=abc.ABCMeta):
+    """A base class for composite config values that can be parsed and serialized from/to a string."""
+
+    @classmethod
+    @abc.abstractmethod
+    def from_string(cls, value: str) -> Self:
+        pass
+
+    @abc.abstractmethod
+    def __str__(self) -> str:
+        pass

scaler/config/section/cluster.py

@@ -0,0 +1,66 @@
+import dataclasses
+import socket
+from typing import Optional
+
+from scaler.config import defaults
+from scaler.config.common.logging import LoggingConfig
+from scaler.config.common.worker import WorkerConfig
+from scaler.config.config_class import ConfigClass
+from scaler.config.types.object_storage_server import ObjectStorageAddressConfig
+from scaler.config.types.worker import WorkerNames
+from scaler.config.types.zmq import ZMQConfig
+from scaler.utility.event_loop import EventLoopType
+
+
+@dataclasses.dataclass
+class ClusterConfig(ConfigClass):
+    scheduler_address: ZMQConfig = dataclasses.field(
+        metadata=dict(positional=True, help="the scheduler address to connect to")
+    )
+    object_storage_address: Optional[ObjectStorageAddressConfig] = dataclasses.field(
+        default=None,
+        metadata=dict(
+            short="-osa",
+            help=(
+                "the object storage server address, e.g. tcp://localhost:2346. "
+                "if not specified, uses the address provided by the scheduler"
+            ),
+        ),
+    )
+    preload: Optional[str] = dataclasses.field(
+        default=None,
+        metadata=dict(
+            help='optional module init in the form "pkg.mod:func(arg1, arg2)" executed in each processor before tasks'
+        ),
+    )
+    worker_names: WorkerNames = dataclasses.field(
+        default_factory=WorkerNames,
+        metadata=dict(
+            short="-wn", help="a comma-separated list of worker names to replace default worker names (host names)"
+        ),
+    )
+    num_of_workers: int = dataclasses.field(
+        default=defaults.DEFAULT_NUMBER_OF_WORKER, metadata=dict(short="-n", help="the number of workers in cluster")
+    )
+    event_loop: str = dataclasses.field(
+        default="builtin",
+        metadata=dict(short="-el", choices=EventLoopType.allowed_types(), help="select the event loop type"),
+    )
+
+    worker_io_threads: int = dataclasses.field(
+        default=defaults.DEFAULT_IO_THREADS,
+        metadata=dict(short="-wit", help="set the number of io threads for io backend per worker"),
+    )
+    worker_config: WorkerConfig = dataclasses.field(default_factory=WorkerConfig)
+    logging_config: LoggingConfig = dataclasses.field(default_factory=LoggingConfig)
+
+    def __post_init__(self):
+        if self.worker_names.names and len(self.worker_names.names) != self.num_of_workers:
+            raise ValueError(
+                f"the number of worker_names ({len(self.worker_names.names)}) "
+                "must match num_of_workers ({self.num_of_workers})."
+            )
+        if not self.worker_names.names:
+            self.worker_names.names = [f"{socket.gethostname().split('.')[0]}" for _ in range(self.num_of_workers)]
+        if self.worker_io_threads <= 0:
+            raise ValueError("worker_io_threads must be a positive integer.")

scaler/config/section/ecs_worker_adapter.py

@@ -0,0 +1,78 @@
+import dataclasses
+from typing import List, Optional
+
+from scaler.config import defaults
+from scaler.config.common.logging import LoggingConfig
+from scaler.config.common.web import WebConfig
+from scaler.config.common.worker import WorkerConfig
+from scaler.config.common.worker_adapter import WorkerAdapterConfig
+from scaler.config.config_class import ConfigClass
+from scaler.utility.event_loop import EventLoopType
+
+
+@dataclasses.dataclass
+class ECSWorkerAdapterConfig(ConfigClass):
+    web_config: WebConfig
+    worker_adapter_config: WorkerAdapterConfig
+    worker_config: WorkerConfig = dataclasses.field(default_factory=WorkerConfig)
+    logging_config: LoggingConfig = dataclasses.field(default_factory=LoggingConfig)
+    event_loop: str = dataclasses.field(
+        default="builtin",
+        metadata=dict(short="-el", choices=EventLoopType.allowed_types(), help="select the event loop type"),
+    )
+
+    worker_io_threads: int = dataclasses.field(
+        default=defaults.DEFAULT_IO_THREADS,
+        metadata=dict(short="-wit", help="set the number of io threads for io backend per worker"),
+    )
+
+    # AWS / ECS specific configuration
+    aws_access_key_id: Optional[str] = dataclasses.field(
+        default=None, metadata=dict(env_var="AWS_ACCESS_KEY_ID", help="AWS access key id")
+    )
+    aws_secret_access_key: Optional[str] = dataclasses.field(
+        default=None, metadata=dict(env_var="AWS_SECRET_ACCESS_KEY", help="AWS secret access key")
+    )
+    aws_region: str = dataclasses.field(default="us-east-1", metadata=dict(help="AWS region for ECS cluster"))
+    ecs_subnets: List[str] = dataclasses.field(
+        default_factory=list,
+        metadata=dict(
+            type=lambda s: [x for x in s.split(",") if x],
+            required=True,
+            help="Comma-separated list of AWS subnet IDs for ECS tasks",
+        ),
+    )
+    ecs_cluster: str = dataclasses.field(default="scaler-cluster", metadata=dict(help="ECS cluster name"))
+    ecs_task_image: str = dataclasses.field(
+        default="public.ecr.aws/v4u8j8r6/scaler:latest", metadata=dict(help="Container image used for ECS tasks")
+    )
+    ecs_python_requirements: str = dataclasses.field(
+        default="tomli;pargraph;parfun;pandas", metadata=dict(help="Python requirements string passed to the ECS task")
+    )
+    ecs_python_version: str = dataclasses.field(default="3.12.11", metadata=dict(help="Python version for ECS task"))
+    ecs_task_definition: str = dataclasses.field(
+        default="scaler-task-definition", metadata=dict(help="ECS task definition")
+    )
+    ecs_task_cpu: int = dataclasses.field(
+        default=4, metadata=dict(help="Number of vCPUs for task (used to derive worker count)")
+    )
+    ecs_task_memory: int = dataclasses.field(default=30, metadata=dict(help="Task memory in GB for Fargate"))
+
+    def __post_init__(self):
+        # Validate numeric and collection values
+        if self.ecs_task_cpu <= 0:
+            raise ValueError("ecs_task_cpu must be a positive integer.")
+        if self.ecs_task_memory <= 0:
+            raise ValueError("ecs_task_memory must be a positive integer.")
+        if not isinstance(self.ecs_subnets, list) or len(self.ecs_subnets) == 0:
+            raise ValueError("ecs_subnets must be a non-empty list of subnet ids.")
+
+        # Validate required strings
+        if not self.ecs_cluster:
+            raise ValueError("ecs_cluster cannot be an empty string.")
+        if not self.ecs_task_definition:
+            raise ValueError("ecs_task_definition cannot be an empty string.")
+        if not self.ecs_task_image:
+            raise ValueError("ecs_task_image cannot be an empty string.")
+        if self.worker_io_threads <= 0:
+            raise ValueError("worker_io_threads must be a positive integer.")

scaler/config/section/native_worker_adapter.py

@@ -0,0 +1,30 @@
+import dataclasses
+
+from scaler.config import defaults
+from scaler.config.common.logging import LoggingConfig
+from scaler.config.common.web import WebConfig
+from scaler.config.common.worker import WorkerConfig
+from scaler.config.common.worker_adapter import WorkerAdapterConfig
+from scaler.config.config_class import ConfigClass
+from scaler.utility.event_loop import EventLoopType
+
+
+@dataclasses.dataclass
+class NativeWorkerAdapterConfig(ConfigClass):
+    web_config: WebConfig
+    worker_adapter_config: WorkerAdapterConfig
+    worker_config: WorkerConfig = dataclasses.field(default_factory=WorkerConfig)
+    logging_config: LoggingConfig = dataclasses.field(default_factory=LoggingConfig)
+    event_loop: str = dataclasses.field(
+        default="builtin",
+        metadata=dict(short="-el", choices=EventLoopType.allowed_types(), help="select the event loop type"),
+    )
+
+    worker_io_threads: int = dataclasses.field(
+        default=defaults.DEFAULT_IO_THREADS,
+        metadata=dict(short="-wit", help="set the number of io threads for io backend per worker"),
+    )
+
+    def __post_init__(self) -> None:
+        if self.worker_io_threads <= 0:
+            raise ValueError("worker_io_threads must be a positive integer.")

scaler/config/section/object_storage_server.py

@@ -0,0 +1,13 @@
+import dataclasses
+
+from scaler.config.config_class import ConfigClass
+from scaler.config.types.object_storage_server import ObjectStorageAddressConfig
+
+
+@dataclasses.dataclass
+class ObjectStorageServerConfig(ConfigClass):
+    object_storage_address: ObjectStorageAddressConfig = dataclasses.field(
+        metadata=dict(
+            positional=True, help="specify the object storage server address to listen to, e.g. tcp://localhost:2345."
+        )
+    )