idegym-api 0.9.0__tar.gz

idegym_api-0.9.0/.gitignore

@@ -0,0 +1,294 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+### PyCharm template
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/dataSources.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Module files
+*.iml
+
+# Project structure
+.idea/**/misc.xml
+.idea/**/modules.xml
+.idea/pySourceRootDetection.xml
+.idea/**/inspectionProfiles/
+.idea/**/runConfigurations/
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### Linux template
+# General
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS template
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### Archives template
+# It's better to unpack these files and commit the raw source because
+# git has its own built in compression methods.
+*.7z
+*.jar
+*.rar
+*.zip
+!plugins/pycharm/project-opener/project-opener.zip
+!plugins/idea/project-opener/project-opener.zip
+*.gz
+*.gzip
+*.tgz
+*.bzip
+*.bzip2
+*.bz2
+*.xz
+*.lzma
+*.cab
+*.xar
+*.zst
+*.tzst
+
+# Packing-only formats
+*.iso
+*.tar
+
+# Package management formats
+*.dmg
+*.xpi
+*.gem
+*.deb
+*.rpm
+*.msi
+*.msm
+*.msp
+*.txz
+
+### Dev Container template
+.*.temp.dockerfile
+
+### Project template
+.project/
+/test-results.xml
+examples/*.json
+examples/**/*.patch

idegym_api-0.9.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: idegym-api
+Version: 0.9.0
+Summary: IdeGYM API
+Author-email: Daniil Mironov <daniil.mironov@jetbrains.com>, Ozren Dabić <ozren.dabic@jetbrains.com>, Vladimir Poliakov <vladimir.poliakov@jetbrains.com>, Vseslav Kasatskii <vseslav.kasatskii@jetbrains.com>
+Requires-Python: >=3.12
+Requires-Dist: idegym-common-utils>=0.9.0
+Requires-Dist: kubernetes>=35.0.0
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: structlog>=25.4.0

idegym_api-0.9.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "idegym-api"
+version = "0.9.0"
+description = "IdeGYM API"
+authors = [
+    { name = "Daniil Mironov", email = "daniil.mironov@jetbrains.com" },
+    { name = "Ozren Dabić", email = "ozren.dabic@jetbrains.com" },
+    { name = "Vladimir Poliakov", email = "vladimir.poliakov@jetbrains.com" },
+    { name = "Vseslav Kasatskii", email = "vseslav.kasatskii@jetbrains.com" },
+]
+requires-python = ">=3.12"
+dependencies = ["idegym-common-utils>=0.9.0", "kubernetes>=35.0.0", "pydantic>=2.10.6", "pyyaml>=6.0.2", "structlog>=25.4.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/idegym"]

idegym_api-0.9.0/src/idegym/api/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("idegym-api")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"
+
+if __version__ == "0.0.0.dev0":
+    __version__ = "latest"

idegym_api-0.9.0/src/idegym/api/auth.py

@@ -0,0 +1,21 @@
+from base64 import b64encode
+from typing import Optional
+
+from pydantic import BaseModel, Field, SecretStr
+
+
+class BasicAuth(BaseModel):
+    """Basic HTTP authentication credentials. Both fields are excluded from serialization."""
+
+    username: Optional[str] = Field(default=None, exclude=True)
+    password: Optional[SecretStr] = Field(default=None, exclude=True)
+
+    @property
+    def base64(self) -> Optional[str]:
+        """Returns Base64-encoded 'username:password' string, or None if username is not set."""
+        if not self.username:
+            return None
+        password = self.password.get_secret_value() if self.password else ""
+        value = self.username + ":" + password
+        encoded = value.encode()
+        return b64encode(encoded).decode()

idegym_api-0.9.0/src/idegym/api/capabilities.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel, Field
+
+
+class CapabilitiesResponse(BaseModel):
+    plugins: list[str] = Field(description="Names of server plugins loaded in the running container")

idegym_api-0.9.0/src/idegym/api/config.py

@@ -0,0 +1,203 @@
+from os.path import abspath, join
+from tempfile import gettempdir
+from typing import Optional
+
+from idegym.api.auth import BasicAuth
+from idegym.api.memory import MemoryQuantity
+from idegym.api.type import Duration, HttpUrl, IPvAddress, LogLevelName
+from pydantic import BaseModel, Field, field_validator
+
+
+class ServerConfig(BaseModel):
+    host: IPvAddress = Field(default="0.0.0.0")
+    port: int = Field(ge=0, le=65535, default=8000)
+    response_buffer_size: MemoryQuantity = Field(ge=0, default=MemoryQuantity(mi=8))
+    shutdown_delay: Duration = Field(default=Duration(seconds=30))
+
+
+class LoggingConfig(BaseModel):
+    level: LogLevelName = Field(default="INFO")
+    json_format: bool = Field(default=False)
+    file_path: str = Field(default=join(gettempdir(), "idegym.log"))
+    max_file_size: MemoryQuantity = Field(ge=0, default=MemoryQuantity(mi=10))
+    max_file_count: int = Field(description="Number of log file backups to keep", ge=0, default=5)
+
+    @field_validator("file_path")
+    def validate_file_path(cls, value: str) -> str:
+        path = value.strip() if value else None
+        if not path:
+            field = cls.__pydantic_fields__["file_path"]
+            return field.default
+        else:
+            return abspath(path)
+
+
+class ProjectConfig(BaseModel):
+    path: str = Field(default=".project")
+    archive: Optional[str] = Field(default=None)
+
+    @field_validator("path")
+    def validate_path(cls, value: str) -> str:
+        path = value.strip() if value else None
+        if not path:
+            field = cls.__pydantic_fields__["path"]
+            return field.default
+        else:
+            return abspath(path)
+
+    @field_validator("archive")
+    def validate_archive_path(cls, value: Optional[str]) -> Optional[str]:
+        path = value.strip() if value else None
+        if not path:
+            field = cls.__pydantic_fields__["archive"]
+            return field.default
+        else:
+            return abspath(path)
+
+
+class DatabaseConfig(BaseModel):
+    host: str = Field(default="localhost")
+    port: str = Field(default="5432")
+    user: str = Field(default="postgres")
+    password: str = Field(default="postgres")
+    db: str = Field(default="idegym")
+    clean_database: bool = Field(description="Drop and recreate all tables on startup", default=False)
+
+    @property
+    def url(self) -> str:
+        return f"postgresql+asyncpg://{self.user}:{self.password}@{self.host}:{self.port}/{self.db}"
+
+
+class SQLAlchemyConfig(BaseModel):
+    pool_size: int = Field(ge=0, default=20)
+    max_overflow: int = Field(ge=0, default=5)
+    pool_recycle: int = Field(ge=-1, default=1800, description="Connection recycling interval in seconds")
+    pool_timeout: int = Field(gt=0, default=1200, description="Connection acquisition timeout in seconds")
+    pool_pre_ping: bool = Field(default=True)
+
+
+class AsyncioConfig(BaseModel):
+    debug: bool = Field(default=False)
+    dump_interval: int = Field(description="Interval in seconds between asyncio task dumps", ge=1, default=300)
+
+
+class NodePoolConfig(BaseModel):
+    enabled: bool = Field(description="Enable dedicated node pool scheduling", default=False)
+    taint_key: str = Field(description="Taint key applied to dedicated pool nodes", default="jetbrains.com/idegym")
+    preference_weight: int = Field(
+        description="Weight (1-100) for preferring dedicated pool nodes", ge=1, le=100, default=100
+    )
+
+
+class ResourcesConfig(BaseModel):
+    default_cpu_request: float = Field(description="Default CPU cores per environment", ge=0, default=1.0)
+    default_ram_request: float = Field(description="Default RAM per environment in GB", ge=0, default=2.0)
+
+
+class ConnectionLimitsConfig(BaseModel):
+    max_connections_or_asyncio_tasks: int = Field(
+        description="The maximum number of concurrent connections that may be established or asyncio tasks in uvicorn.",
+        ge=1,
+        default=1500,
+    )
+    unhealthy_connections_or_asyncio_tasks: int = Field(
+        description="The maximum number of concurrent connections that"
+        " may be established or asyncio tasks in uvicorn after which orchestrator becomes unhealthy.",
+        ge=1,
+        default=1000,
+    )
+    max_keepalive_connections: int = Field(
+        description="Allow the connection pool to maintain keep-alive connections below this point."
+        "Should be less than or equal to `max_connections`",
+        ge=1,
+        default=20,
+    )
+    keepalive_expiry: float = Field(
+        description="Time limit on idle keep-alive connections in seconds.", ge=1.0, default=5.0
+    )
+
+
+class TracingConfig(BaseModel):
+    endpoint: Optional[HttpUrl] = Field(description="OTLP HTTP endpoint for traces", default=None)
+    timeout: float = Field(description="Timeout for sending traces in seconds", ge=0, default=10)
+    auth: BasicAuth = Field(default_factory=BasicAuth)
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.endpoint)
+
+
+class OTELConfig(BaseModel):
+    service_name: Optional[str] = Field(default=None)
+    tracing: TracingConfig = Field(default_factory=TracingConfig)
+    attributes: dict[str, str] = Field(description="Extra attributes added to all spans", default_factory=dict)
+
+
+class PodSnapshotConfig(BaseModel):
+    enabled: bool = Field(default=False)
+    service_account_name: str = Field(
+        description="Kubernetes service account shared by all snapshot-enabled pods", default="idegym"
+    )
+
+
+class WatcherConfig(BaseModel):
+    cleanup_interval: Duration = Field(default=Duration(seconds=60))
+    inactive_timeout: Duration = Field(
+        description="Inactivity timeout after which idle servers/clients are cleaned up",
+        default=Duration(minutes=10),
+    )
+    finished_timeout: Duration = Field(
+        description="How long to keep finished servers before deleting them",
+        default=Duration(minutes=5),
+    )
+    request_max_age: Duration = Field(
+        description="Maximum age of request records to retain",
+        default=Duration(days=14),
+    )
+    request_stale: Duration = Field(
+        description="Age after which IN_PROGRESS requests are marked as finished",
+        default=Duration(hours=24),
+    )
+
+
+class OrchestratorConfig(BaseModel):
+    host: IPvAddress = Field(default="0.0.0.0")
+    port: int = Field(ge=0, le=65535, default=8000)
+    workers: int = Field(description="Number of uvicorn worker processes", ge=1, default=1)
+    prometheus_multiproc_dir: str = Field(
+        description="Directory for Prometheus multiprocess metric files",
+        default=join(gettempdir(), "idegym", "prometheus"),
+    )
+    database: DatabaseConfig = Field(default_factory=DatabaseConfig)
+    sqlalchemy: SQLAlchemyConfig = Field(default_factory=SQLAlchemyConfig)
+    asyncio: AsyncioConfig = Field(default_factory=AsyncioConfig)
+    resources: ResourcesConfig = Field(default_factory=ResourcesConfig)
+    node_pool: NodePoolConfig = Field(default_factory=NodePoolConfig)
+    watcher: WatcherConfig = Field(default_factory=WatcherConfig)
+    client_request_timeout: float = Field(
+        description="Client request read timeout in seconds",
+        default=60.0 * 60,  # 1 hour
+    )
+    connection_limits: ConnectionLimitsConfig = Field(default_factory=ConnectionLimitsConfig)
+    pod_snapshot: PodSnapshotConfig = Field(default_factory=PodSnapshotConfig)
+    enable_fifo_server_reuse: bool = Field(
+        description="Enable FIFO queue for server reuse to ensure fair provisioning",
+        default=False,
+    )
+
+    @field_validator("prometheus_multiproc_dir")
+    def validate_prometheus_multiproc_dir(cls, value: str) -> str:
+        path = value.strip() if value else None
+        if not path:
+            field = cls.__pydantic_fields__["prometheus_multiproc_dir"]
+            return field.default
+        else:
+            return abspath(path)
+
+
+class Config(BaseModel):
+    server: ServerConfig = Field(default_factory=ServerConfig)
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+    project: ProjectConfig = Field(default_factory=ProjectConfig)
+    otel: OTELConfig = Field(default_factory=OTELConfig)
+    orchestrator: OrchestratorConfig = Field(default_factory=OrchestratorConfig)

idegym_api-0.9.0/src/idegym/api/cpu.py

@@ -0,0 +1,144 @@
+from functools import total_ordering
+from re import Pattern, compile
+from typing import Any, ClassVar, Union
+
+from kubernetes.utils import parse_quantity
+from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler
+from pydantic.json_schema import JsonSchemaValue
+from pydantic_core import core_schema
+
+
+@total_ordering
+class CpuQuantity:
+    """
+    CPU quantity supporting fractional/whole cores and millicore notation.
+
+    Stores values internally as integer millicores.
+    Accepts strings like ``"500m"``/``"1.5"`` or
+    numeric cores as ``int``/``float``.
+    """
+
+    PATTERN: ClassVar[Pattern] = compile(r"^(\d*\.?\d+)(m)?$")
+
+    def __init__(self, *, cores: int | float = 0, millicores: int = 0):
+        total = round(cores * 1000) + millicores
+        if total < 0:
+            raise ValueError("CpuQuantity cannot be negative")
+        self._millicores = total
+
+    @classmethod
+    def parse(cls, value: str) -> "CpuQuantity":
+        try:
+            normalized = value.strip()
+            matcher = cls.PATTERN.match(normalized)
+            if not matcher:
+                raise ValueError(f"'{value}' does not match CPU quantity pattern")
+            amount, suffix = matcher.groups()
+            if suffix == "m" and "." in amount:
+                raise ValueError(f"Millicore values must be integers: {amount}")
+            cores = parse_quantity(normalized)
+            if cores < 0:
+                raise ValueError("CpuQuantity cannot be negative")
+            return cls(millicores=int(cores * 1000))
+        except ValueError:
+            raise
+        except Exception as ex:
+            raise ValueError(f"'{value}' is not a valid CPU quantity") from ex
+
+    @property
+    def millicores(self) -> int:
+        return self._millicores
+
+    @property
+    def cores(self) -> float:
+        return self._millicores / 1000
+
+    def __eq__(self, other: object) -> bool:
+        if self is other:
+            return True
+        match other:
+            case CpuQuantity():
+                return self._millicores == other._millicores
+            case int() | float():
+                return self._millicores == round(other * 1000)
+            case str():
+                return self._millicores == CpuQuantity.parse(other)._millicores
+            case _:
+                return False
+
+    def __lt__(self, other: Union["CpuQuantity", int, float, str]) -> bool:
+        match other:
+            case CpuQuantity():
+                return self._millicores < other._millicores
+            case int() | float():
+                return self._millicores < round(other * 1000)
+            case str():
+                return self._millicores < CpuQuantity.parse(other)._millicores
+            case _:
+                return NotImplemented
+
+    def __str__(self) -> str:
+        if self._millicores % 1000 == 0:
+            return str(self._millicores // 1000)
+        return f"{self._millicores}m"
+
+    def __repr__(self) -> str:
+        return f"CpuQuantity(millicores={self._millicores})"
+
+    def __hash__(self) -> int:
+        return hash(self._millicores)
+
+    @classmethod
+    def validate(cls, value: Union["CpuQuantity", int, float, str]) -> "CpuQuantity":
+        match value:
+            case cls():
+                return value
+            case int() | float():
+                return cls(cores=value)
+            case str():
+                return cls.parse(value)
+            case _:
+                raise ValueError(f"Cannot convert {value} to {cls.__name__}")
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        _source_type: Any,
+        _handler: GetCoreSchemaHandler,
+    ) -> core_schema.CoreSchema:
+        return core_schema.union_schema(
+            [
+                core_schema.is_instance_schema(cls),
+                core_schema.chain_schema(
+                    [
+                        core_schema.int_schema(),
+                        core_schema.no_info_plain_validator_function(cls.validate),
+                    ]
+                ),
+                core_schema.chain_schema(
+                    [
+                        core_schema.float_schema(),
+                        core_schema.no_info_plain_validator_function(cls.validate),
+                    ]
+                ),
+                core_schema.chain_schema(
+                    [
+                        core_schema.str_schema(),
+                        core_schema.no_info_plain_validator_function(cls.parse),
+                    ]
+                ),
+            ],
+            serialization=core_schema.plain_serializer_function_ser_schema(str),
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls,
+        _core_schema: core_schema.CoreSchema,
+        _handler: GetJsonSchemaHandler,
+    ) -> JsonSchemaValue:
+        return {
+            "type": "string",
+            "description": "CPU quantity in cores or millicores (e.g. '500m', '1', '2.5')",
+            "examples": ["100m", "250m", "500m", "1", "1500m", "2"],
+        }