fal 1.2.1__py3-none-any.whl → 1.7.2__py3-none-any.whl

fal/sdk.py

@@ -5,7 +5,7 @@ from contextlib import ExitStack
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
 from enum import Enum
-from typing import Any, Callable, Generic, Iterator, Literal, TypeVar
+from typing import Any, Callable, Generic, Iterator, Literal, Optional, TypeVar
 
 import grpc
 import isolate_proto
@@ -214,7 +214,7 @@ class AliasInfo:
 class RunnerInfo:
     runner_id: str
     in_flight_requests: int
-    expiration_countdown: int
+    expiration_countdown: Optional[int]
     uptime: timedelta
 
 
@@ -275,6 +275,33 @@ class KeyScope(enum.Enum):
             raise ValueError(f"Unknown KeyScope: {proto}")
 
 
+class DeploymentStrategy(enum.Enum):
+    RECREATE = "recreate"
+    ROLLING = "rolling"
+
+    @staticmethod
+    def from_proto(
+        proto: isolate_proto.DeploymentStrategy.ValueType | None,
+    ) -> DeploymentStrategy:
+        if proto is None:
+            return DeploymentStrategy.RECREATE
+
+        if proto is isolate_proto.DeploymentStrategy.RECREATE:
+            return DeploymentStrategy.RECREATE
+        elif proto is isolate_proto.DeploymentStrategy.ROLLING:
+            return DeploymentStrategy.ROLLING
+        else:
+            raise ValueError(f"Unknown DeploymentStrategy: {proto}")
+
+    def to_proto(self) -> isolate_proto.DeploymentStrategy.ValueType:
+        if self is DeploymentStrategy.RECREATE:
+            return isolate_proto.DeploymentStrategy.RECREATE
+        elif self is DeploymentStrategy.ROLLING:
+            return isolate_proto.DeploymentStrategy.ROLLING
+        else:
+            raise ValueError(f"Unknown DeploymentStrategy: {self}")
+
+
 @from_grpc.register(isolate_proto.ApplicationInfo)
 def _from_grpc_application_info(
     message: isolate_proto.ApplicationInfo,
@@ -317,7 +344,9 @@ def _from_grpc_runner_info(message: isolate_proto.RunnerInfo) -> RunnerInfo:
     return RunnerInfo(
         runner_id=message.runner_id,
         in_flight_requests=message.in_flight_requests,
-        expiration_countdown=message.expiration_countdown,
+        expiration_countdown=message.expiration_countdown
+        if message.HasField("expiration_countdown")
+        else None,
         uptime=timedelta(seconds=message.uptime),
     )
 
@@ -362,7 +391,8 @@ def _from_grpc_hosted_run_result(
 
 @dataclass
 class MachineRequirements:
-    machine_type: str
+    machine_types: list[str]
+    num_gpus: int | None = field(default=None)
     keep_alive: int = FAL_SERVERLESS_DEFAULT_KEEP_ALIVE
     base_image: str | None = None
     exposed_port: int | None = None
@@ -371,6 +401,17 @@ class MachineRequirements:
     max_concurrency: int | None = None
     max_multiplexing: int | None = None
     min_concurrency: int | None = None
+    request_timeout: int | None = None
+
+    def __post_init__(self):
+        if isinstance(self.machine_types, str):
+            self.machine_types = [self.machine_types]
+
+        if not isinstance(self.machine_types, list):
+            raise ValueError("machine_types must be a list of strings.")
+
+        if not self.machine_types:
+            raise ValueError("No machine type provided.")
 
 
 @dataclass
@@ -457,11 +498,16 @@ class FalServerlessConnection:
         serialization_method: str = _DEFAULT_SERIALIZATION_METHOD,
         machine_requirements: MachineRequirements | None = None,
         metadata: dict[str, Any] | None = None,
+        deployment_strategy: Literal["recreate", "rolling"] = "recreate",
+        scale: bool = True,
     ) -> Iterator[isolate_proto.RegisterApplicationResult]:
         wrapped_function = to_serialized_object(function, serialization_method)
         if machine_requirements:
             wrapped_requirements = isolate_proto.MachineRequirements(
-                machine_type=machine_requirements.machine_type,
+                # NOTE: backwards compatibility with old API
+                machine_type=machine_requirements.machine_types[0],
+                machine_types=machine_requirements.machine_types,
+                num_gpus=machine_requirements.num_gpus,
                 keep_alive=machine_requirements.keep_alive,
                 base_image=machine_requirements.base_image,
                 exposed_port=machine_requirements.exposed_port,
@@ -472,6 +518,7 @@ class FalServerlessConnection:
                 max_concurrency=machine_requirements.max_concurrency,
                 min_concurrency=machine_requirements.min_concurrency,
                 max_multiplexing=machine_requirements.max_multiplexing,
+                request_timeout=machine_requirements.request_timeout,
             )
         else:
             wrapped_requirements = None
@@ -488,6 +535,10 @@ class FalServerlessConnection:
             struct_metadata = isolate_proto.Struct()
             struct_metadata.update(metadata)
 
+        deployment_strategy_proto = DeploymentStrategy[
+            deployment_strategy.upper()
+        ].to_proto()
+
         request = isolate_proto.RegisterApplicationRequest(
             function=wrapped_function,
             environments=environments,
@@ -495,6 +546,8 @@ class FalServerlessConnection:
             application_name=application_name,
             auth_mode=auth_mode,
             metadata=struct_metadata,
+            deployment_strategy=deployment_strategy_proto,
+            scale=scale,
         )
         for partial_result in self.stub.RegisterApplication(request):
             yield from_grpc(partial_result)
@@ -546,7 +599,10 @@ class FalServerlessConnection:
         wrapped_function = to_serialized_object(function, serialization_method)
         if machine_requirements:
             wrapped_requirements = isolate_proto.MachineRequirements(
-                machine_type=machine_requirements.machine_type,
+                # NOTE: backwards compatibility with old API
+                machine_type=machine_requirements.machine_types[0],
+                machine_types=machine_requirements.machine_types,
+                num_gpus=machine_requirements.num_gpus,
                 keep_alive=machine_requirements.keep_alive,
                 base_image=machine_requirements.base_image,
                 exposed_port=machine_requirements.exposed_port,
@@ -557,6 +613,7 @@ class FalServerlessConnection:
                 max_concurrency=machine_requirements.max_concurrency,
                 max_multiplexing=machine_requirements.max_multiplexing,
                 min_concurrency=machine_requirements.min_concurrency,
+                request_timeout=machine_requirements.request_timeout,
             )
         else:
             wrapped_requirements = None
@@ -629,3 +686,7 @@ class FalServerlessConnection:
             )
             for secret in response.secrets
         ]
+
+    def kill_runner(self, runner_id: str) -> None:
+        request = isolate_proto.KillRunnerRequest(runner_id=runner_id)
+        self.stub.KillRunner(request)

fal/toolkit/file/file.py

@@ -8,6 +8,7 @@ from urllib.parse import urlparse
 from zipfile import ZipFile
 
 import pydantic
+from fastapi import Request
 
 # https://github.com/pydantic/pydantic/pull/2573
 if not hasattr(pydantic, "__version__") or pydantic.__version__.startswith("1."):
@@ -21,9 +22,11 @@ else:
 from pydantic import BaseModel, Field
 
 from fal.toolkit.file.providers.fal import (
+    LIFECYCLE_PREFERENCE,
     FalCDNFileRepository,
     FalFileRepository,
     FalFileRepositoryV2,
+    FalFileRepositoryV3,
     InMemoryRepository,
 )
 from fal.toolkit.file.providers.gcp import GoogleStorageRepository
@@ -36,6 +39,7 @@ FileRepositoryFactory = Callable[[], FileRepository]
 BUILT_IN_REPOSITORIES: dict[RepositoryId, FileRepositoryFactory] = {
     "fal": lambda: FalFileRepository(),
     "fal_v2": lambda: FalFileRepositoryV2(),
+    "fal_v3": lambda: FalFileRepositoryV3(),
     "in_memory": lambda: InMemoryRepository(),
     "gcp_storage": lambda: GoogleStorageRepository(),
     "r2": lambda: R2Repository(),
@@ -43,7 +47,10 @@ BUILT_IN_REPOSITORIES: dict[RepositoryId, FileRepositoryFactory] = {
 }
 
 
-def get_builtin_repository(id: RepositoryId) -> FileRepository:
+def get_builtin_repository(id: RepositoryId | FileRepository) -> FileRepository:
+    if isinstance(id, FileRepository):
+        return id
+
     if id not in BUILT_IN_REPOSITORIES.keys():
         raise ValueError(f'"{id}" is not a valid built-in file repository')
     return BUILT_IN_REPOSITORIES[id]()
@@ -51,7 +58,9 @@ def get_builtin_repository(id: RepositoryId) -> FileRepository:
 
 get_builtin_repository.__module__ = "__main__"
 
-DEFAULT_REPOSITORY: FileRepository | RepositoryId = "fal"
+DEFAULT_REPOSITORY: FileRepository | RepositoryId = "fal_v3"
+FALLBACK_REPOSITORY: FileRepository | RepositoryId = "cdn"
+OBJECT_LIFECYCLE_PREFERENCE_KEY = "x-fal-object-lifecycle-preference"
 
 
 class File(BaseModel):
@@ -116,7 +125,8 @@ class File(BaseModel):
             url=url,
             content_type=None,
             file_name=None,
-            repository=DEFAULT_REPOSITORY,
+            file_size=None,
+            file_data=None,
         )
 
     @classmethod
@@ -126,17 +136,38 @@ class File(BaseModel):
         content_type: Optional[str] = None,
         file_name: Optional[str] = None,
         repository: FileRepository | RepositoryId = DEFAULT_REPOSITORY,
+        fallback_repository: Optional[
+            FileRepository | RepositoryId
+        ] = FALLBACK_REPOSITORY,
+        request: Optional[Request] = None,
+        save_kwargs: Optional[dict] = None,
+        fallback_save_kwargs: Optional[dict] = None,
     ) -> File:
-        repo = (
-            repository
-            if isinstance(repository, FileRepository)
-            else get_builtin_repository(repository)
-        )
+        repo = get_builtin_repository(repository)
+
+        save_kwargs = save_kwargs or {}
+        fallback_save_kwargs = fallback_save_kwargs or {}
 
         fdata = FileData(data, content_type, file_name)
 
+        object_lifecycle_preference = (
+            request_lifecycle_preference(request) or LIFECYCLE_PREFERENCE.get()
+        )
+
+        try:
+            url = repo.save(fdata, object_lifecycle_preference, **save_kwargs)
+        except Exception:
+            if not fallback_repository:
+                raise
+
+            fallback_repo = get_builtin_repository(fallback_repository)
+
+            url = fallback_repo.save(
+                fdata, object_lifecycle_preference, **fallback_save_kwargs
+            )
+
         return cls(
-            url=repo.save(fdata),
+            url=url,
             content_type=fdata.content_type,
             file_name=fdata.file_name,
             file_size=len(data),
@@ -149,14 +180,56 @@ class File(BaseModel):
         path: str | Path,
         content_type: Optional[str] = None,
         repository: FileRepository | RepositoryId = DEFAULT_REPOSITORY,
+        multipart: bool | None = None,
+        fallback_repository: Optional[
+            FileRepository | RepositoryId
+        ] = FALLBACK_REPOSITORY,
+        request: Optional[Request] = None,
+        save_kwargs: Optional[dict] = None,
+        fallback_save_kwargs: Optional[dict] = None,
     ) -> File:
         file_path = Path(path)
         if not file_path.exists():
             raise FileNotFoundError(f"File {file_path} does not exist")
-        with open(file_path, "rb") as f:
-            data = f.read()
-        return File.from_bytes(
-            data, content_type, file_name=file_path.name, repository=repository
+
+        repo = get_builtin_repository(repository)
+
+        save_kwargs = save_kwargs or {}
+        fallback_save_kwargs = fallback_save_kwargs or {}
+
+        content_type = content_type or "application/octet-stream"
+        object_lifecycle_preference = (
+            request_lifecycle_preference(request) or LIFECYCLE_PREFERENCE.get()
+        )
+
+        try:
+            url, data = repo.save_file(
+                file_path,
+                content_type=content_type,
+                multipart=multipart,
+                object_lifecycle_preference=object_lifecycle_preference,
+                **save_kwargs,
+            )
+        except Exception:
+            if not fallback_repository:
+                raise
+
+            fallback_repo = get_builtin_repository(fallback_repository)
+
+            url, data = fallback_repo.save_file(
+                file_path,
+                content_type=content_type,
+                multipart=multipart,
+                object_lifecycle_preference=object_lifecycle_preference,
+                **fallback_save_kwargs,
+            )
+
+        return cls(
+            url=url,
+            file_data=data.data if data else None,
+            content_type=content_type,
+            file_name=file_path.name,
+            file_size=file_path.stat().st_size,
         )
 
     def as_bytes(self) -> bytes:
@@ -206,3 +279,20 @@ class CompressedFile(File):
     def __del__(self):
         if self.extract_dir:
             shutil.rmtree(self.extract_dir)
+
+
+def request_lifecycle_preference(request: Optional[Request]) -> dict[str, str] | None:
+    import json
+
+    if request is None:
+        return None
+
+    preference_str = request.headers.get(OBJECT_LIFECYCLE_PREFERENCE_KEY)
+    if preference_str is None:
+        return None
+
+    try:
+        return json.loads(preference_str)
+    except Exception as e:
+        print(f"Failed to parse object lifecycle preference: {e}")
+        return None