fractal-server 2.16.5__py3-none-any.whl → 2.17.0__py3-none-any.whl

fractal_server/config/_data.py

@@ -0,0 +1,68 @@
+from enum import StrEnum
+from typing import Self
+
+from pydantic import model_validator
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+from ._settings_config import SETTINGS_CONFIG_DICT
+from fractal_server.types import AbsolutePathStr
+
+
+class DataAuthScheme(StrEnum):
+    VIEWER_PATHS = "viewer-paths"
+    USERS_FOLDERS = "users-folders"
+    NONE = "none"
+
+
+class DataSettings(BaseSettings):
+    """
+    Settings for the `fractal-data` integration.
+    """
+
+    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)
+
+    FRACTAL_DATA_AUTH_SCHEME: DataAuthScheme = "none"
+    """
+    Defines how the list of allowed viewer paths is built.
+
+    This variable affects the `GET /auth/current-user/allowed-viewer-paths/`
+    response, which is then consumed by
+    [fractal-data](https://github.com/fractal-analytics-platform/fractal-data).
+
+    Options:
+
+    - "viewer-paths": The list of allowed viewer paths will include the user's
+      `project_dir` along with any path defined in user groups' `viewer_paths`
+      attributes.
+    - "users-folders": The list will consist of the user's `project_dir` and a
+       user-specific folder. The user folder is constructed by concatenating
+       the base folder `FRACTAL_DATA_BASE_FOLDER` with the user's profile
+       `username`.
+    - "none": An empty list will be returned, indicating no access to
+       viewer paths. Useful when vizarr viewer is not used.
+    """
+
+    FRACTAL_DATA_BASE_FOLDER: AbsolutePathStr | None = None
+    """
+    Base path to Zarr files that will be served by fractal-vizarr-viewer;
+    This variable is required and used only when
+    FRACTAL_DATA_AUTHORIZATION_SCHEME is set to "users-folders".
+    """
+
+    @model_validator(mode="after")
+    def check(self: Self) -> Self:
+        """
+        `FRACTAL_DATA_BASE_FOLDER` is required when
+        `FRACTAL_DATA_AUTHORIZATION_SCHEME` is set to `"users-folders"`.
+        """
+        if (
+            self.FRACTAL_DATA_AUTH_SCHEME == DataAuthScheme.USERS_FOLDERS
+            and self.FRACTAL_DATA_BASE_FOLDER is None
+        ):
+            raise ValueError(
+                "FRACTAL_DATA_BASE_FOLDER is required when "
+                "FRACTAL_DATA_AUTH_SCHEME is set to "
+                "users-folders"
+            )
+        return self

fractal_server/config/_database.py

@@ -0,0 +1,59 @@
+from pydantic import SecretStr
+from pydantic.types import NonNegativeInt
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+from sqlalchemy.engine import URL
+
+from ._settings_config import SETTINGS_CONFIG_DICT
+from fractal_server.types import NonEmptyStr
+
+
+class DatabaseSettings(BaseSettings):
+    """
+    Minimal set of configurations needed for operating on the database (e.g
+    for schema migrations).
+    """
+
+    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)
+
+    DB_ECHO: bool = False
+    """
+    If `True`, make database operations verbose.
+    """
+    POSTGRES_USER: NonEmptyStr | None = None
+    """
+    User to use when connecting to the PostgreSQL database.
+    """
+    POSTGRES_PASSWORD: SecretStr | None = None
+    """
+    Password to use when connecting to the PostgreSQL database.
+    """
+    POSTGRES_HOST: NonEmptyStr = "localhost"
+    """
+    URL to the PostgreSQL server or path to a UNIX domain socket.
+    """
+    POSTGRES_PORT: NonNegativeInt = 5432
+    """
+    Port number to use when connecting to the PostgreSQL server.
+    """
+    POSTGRES_DB: NonEmptyStr
+    """
+    Name of the PostgreSQL database to connect to.
+    """
+
+    @property
+    def DATABASE_URL(self) -> URL:
+        if self.POSTGRES_PASSWORD is None:
+            password = None
+        else:
+            password = self.POSTGRES_PASSWORD.get_secret_value()
+
+        url = URL.create(
+            drivername="postgresql+psycopg",
+            username=self.POSTGRES_USER,
+            password=password,
+            host=self.POSTGRES_HOST,
+            port=self.POSTGRES_PORT,
+            database=self.POSTGRES_DB,
+        )
+        return url

fractal_server/config/_email.py

@@ -0,0 +1,133 @@
+from typing import Literal
+from typing import Self
+
+from pydantic import BaseModel
+from pydantic import EmailStr
+from pydantic import Field
+from pydantic import model_validator
+from pydantic import SecretStr
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+from ._settings_config import SETTINGS_CONFIG_DICT
+
+
+class PublicEmailSettings(BaseModel):
+    """
+    Schema for `EmailSettings.public`, namely the ready-to-use settings.
+
+    Attributes:
+        sender: Sender email address
+        recipients: List of recipients email address
+        smtp_server: SMTP server address
+        port: SMTP server port
+        password: Sender password
+        instance_name: Name of SMTP server instance
+        use_starttls: Whether to use the security protocol
+        use_login: Whether to use login
+    """
+
+    sender: EmailStr
+    recipients: list[EmailStr] = Field(min_length=1)
+    smtp_server: str
+    port: int
+    password: SecretStr | None = None
+    instance_name: str
+    use_starttls: bool
+    use_login: bool
+
+
+class EmailSettings(BaseSettings):
+    """
+    Class with settings for email-sending feature.
+    """
+
+    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)
+
+    FRACTAL_EMAIL_SENDER: EmailStr | None = None
+    """
+    Address of the OAuth-signup email sender.
+    """
+    FRACTAL_EMAIL_PASSWORD: SecretStr | None = None
+    """
+    Password for the OAuth-signup email sender.
+    """
+    FRACTAL_EMAIL_SMTP_SERVER: str | None = None
+    """
+    SMTP server for the OAuth-signup emails.
+    """
+    FRACTAL_EMAIL_SMTP_PORT: int | None = None
+    """
+    SMTP server port for the OAuth-signup emails.
+    """
+    FRACTAL_EMAIL_INSTANCE_NAME: str | None = None
+    """
+    Fractal instance name, to be included in the OAuth-signup emails.
+    """
+    FRACTAL_EMAIL_RECIPIENTS: str | None = None
+    """
+    Comma-separated list of recipients of the OAuth-signup emails.
+    """
+    FRACTAL_EMAIL_USE_STARTTLS: Literal["true", "false"] = "true"
+    """
+    Whether to use StartTLS when using the SMTP server.
+    Accepted values: 'true', 'false'.
+    """
+    FRACTAL_EMAIL_USE_LOGIN: Literal["true", "false"] = "true"
+    """
+    Whether to use login when using the SMTP server.
+    If 'true', FRACTAL_EMAIL_PASSWORD  must be provided.
+    Accepted values: 'true', 'false'.
+    """
+
+    public: PublicEmailSettings | None = None
+    """
+    The validated field which is actually used in `fractal-server
+    (automatically populated upon creation).
+    """
+
+    @model_validator(mode="after")
+    def validate_email_settings(self: Self) -> Self:
+        """
+        Set `self.public`.
+        """
+
+        email_values = [
+            self.FRACTAL_EMAIL_SENDER,
+            self.FRACTAL_EMAIL_SMTP_SERVER,
+            self.FRACTAL_EMAIL_SMTP_PORT,
+            self.FRACTAL_EMAIL_INSTANCE_NAME,
+            self.FRACTAL_EMAIL_RECIPIENTS,
+        ]
+        if len(set(email_values)) == 1:
+            # All required EMAIL attributes are None
+            pass
+        elif None in email_values:
+            # Not all required EMAIL attributes are set
+            error_msg = (
+                "Invalid FRACTAL_EMAIL configuration. "
+                f"Given values: {email_values}."
+            )
+            raise ValueError(error_msg)
+        else:
+            use_starttls = self.FRACTAL_EMAIL_USE_STARTTLS == "true"
+            use_login = self.FRACTAL_EMAIL_USE_LOGIN == "true"
+
+            if use_login and self.FRACTAL_EMAIL_PASSWORD is None:
+                raise ValueError(
+                    "'FRACTAL_EMAIL_USE_LOGIN' is 'true' but "
+                    "'FRACTAL_EMAIL_PASSWORD' is not provided."
+                )
+
+            self.public = PublicEmailSettings(
+                sender=self.FRACTAL_EMAIL_SENDER,
+                recipients=self.FRACTAL_EMAIL_RECIPIENTS.split(","),
+                smtp_server=self.FRACTAL_EMAIL_SMTP_SERVER,
+                port=self.FRACTAL_EMAIL_SMTP_PORT,
+                password=self.FRACTAL_EMAIL_PASSWORD,
+                instance_name=self.FRACTAL_EMAIL_INSTANCE_NAME,
+                use_starttls=use_starttls,
+                use_login=use_login,
+            )
+
+        return self

fractal_server/config/_main.py

@@ -0,0 +1,78 @@
+import logging
+from typing import Literal
+
+from pydantic import HttpUrl
+from pydantic import SecretStr
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+from ._settings_config import SETTINGS_CONFIG_DICT
+
+
+class Settings(BaseSettings):
+    """
+    Contains all the configuration variables for Fractal Server
+
+    The attributes of this class are set from the environment.
+    """
+
+    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)
+
+    JWT_EXPIRE_SECONDS: int = 180
+    """
+    JWT token lifetime, in seconds.
+    """
+
+    JWT_SECRET_KEY: SecretStr
+    """
+    JWT secret
+
+    ⚠️ **IMPORTANT**: set this variable to a secure string, and do not disclose
+    it.
+    """
+
+    COOKIE_EXPIRE_SECONDS: int = 86400
+    """
+    Cookie token lifetime, in seconds.
+    """
+
+    # Note: we do not use ResourceType here to avoid circular imports
+    FRACTAL_RUNNER_BACKEND: Literal[
+        "local", "slurm_ssh", "slurm_sudo"
+    ] = "local"
+    """
+    Select which runner backend to use.
+    """
+
+    FRACTAL_LOGGING_LEVEL: int = logging.INFO
+    """
+    Logging-level threshold for logging
+
+    Only logs of with this level (or higher) will appear in the console logs.
+    """
+
+    FRACTAL_API_MAX_JOB_LIST_LENGTH: int = 25
+    """
+    Number of ids that can be stored in the `jobsV2` attribute of
+    `app.state`.
+    """
+
+    FRACTAL_GRACEFUL_SHUTDOWN_TIME: int = 30
+    """
+    Waiting time for the shutdown phase of executors
+    """
+
+    FRACTAL_HELP_URL: HttpUrl | None = None
+    """
+    The URL of an instance-specific Fractal help page.
+    """
+
+    FRACTAL_DEFAULT_GROUP_NAME: Literal["All"] | None = None
+    """
+    Name of the default user group.
+
+    If set to `"All"`, then the user group with that name is a special user
+    group (e.g. it cannot be deleted, and new users are automatically added
+    to it). If set to `None` (the default value), then user groups are all
+    equivalent, independently on their name.
+    """

fractal_server/config/_oauth.py

@@ -0,0 +1,69 @@
+from typing import Annotated
+from typing import Self
+
+from pydantic import model_validator
+from pydantic import SecretStr
+from pydantic import StringConstraints
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+from ._settings_config import SETTINGS_CONFIG_DICT
+from fractal_server.types import NonEmptyStr
+
+
+class OAuthSettings(BaseSettings):
+    """
+    Minimal set of configurations needed for operating on the database (e.g
+    for schema migrations).
+    """
+
+    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)
+
+    OAUTH_CLIENT_NAME: (
+        Annotated[
+            NonEmptyStr,
+            StringConstraints(to_lower=True),
+        ]
+        | None
+    ) = None
+    """
+    The name of the client.
+    """
+    OAUTH_CLIENT_ID: SecretStr | None = None
+    """
+    ID of client.
+    """
+    OAUTH_CLIENT_SECRET: SecretStr | None = None
+    """
+    Secret to authorise against the identity provider.
+    """
+    OAUTH_OIDC_CONFIG_ENDPOINT: SecretStr | None = None
+    """
+    OpenID configuration endpoint, for autodiscovery of relevant endpoints.
+    """
+    OAUTH_REDIRECT_URL: str | None = None
+    """
+    String to be used as `redirect_url` argument in
+    `fastapi_users.get_oauth_router`, and then in
+    `httpx_oauth.integrations.fastapi.OAuth2AuthorizeCallback`
+    """
+
+    @model_validator(mode="after")
+    def check_configuration(self: Self) -> Self:
+        if (
+            self.OAUTH_CLIENT_NAME not in ["google", "github", None]
+            and self.OAUTH_OIDC_CONFIG_ENDPOINT is None
+        ):
+            raise ValueError(
+                f"self.OAUTH_OIDC_CONFIG_ENDPOINT=None but "
+                f"{self.OAUTH_CLIENT_NAME=}"
+            )
+        return self
+
+    @property
+    def is_set(self) -> bool:
+        return None not in (
+            self.OAUTH_CLIENT_NAME,
+            self.OAUTH_CLIENT_ID,
+            self.OAUTH_CLIENT_SECRET,
+        )

fractal_server/config/_settings_config.py

@@ -0,0 +1,7 @@
+from pathlib import Path
+
+SETTINGS_CONFIG_DICT = dict(
+    case_sensitive=True,
+    env_file=Path(".fractal_server.env"),
+    extra="ignore",
+)