fal 1.49.1__py3-none-any.whl → 1.57.2__py3-none-any.whl

fal/app.py

@@ -38,6 +38,7 @@ from fal.toolkit.file.providers.fal import LIFECYCLE_PREFERENCE
 
 REALTIME_APP_REQUIREMENTS = ["websockets", "msgpack"]
 REQUEST_ID_KEY = "x-fal-request-id"
+REQUEST_ENDPOINT_KEY = "x-fal-endpoint"
 DEFAULT_APP_FILES_IGNORE = [
     r"\.pyc$",
     r"__pycache__/",
@@ -103,9 +104,7 @@ async def _set_logger_labels(
         code = await res.code()
         assert str(code) == "StatusCode.OK", str(code)
     except BaseException:
-        # NOTE hiding this for now to not print on every request
-        # logger.debug("Failed to set logger labels", exc_info=True)
-        pass
+        logger.debug("Failed to set logger labels", exc_info=True)
 
 
 def wrap_app(cls: type[App], **kwargs) -> IsolatedFunction:
@@ -136,6 +135,7 @@ def wrap_app(cls: type[App], **kwargs) -> IsolatedFunction:
         local_python_modules=cls.local_python_modules,
         machine_type=cls.machine_type,
         num_gpus=cls.num_gpus,
+        regions=cls.regions,
         **cls.host_kwargs,
         **kwargs,
         metadata=metadata,
@@ -374,6 +374,7 @@ class App(BaseServable):
     local_python_modules: ClassVar[list[str]] = []
     machine_type: ClassVar[str | list[str]] = "S"
     num_gpus: ClassVar[int | None] = None
+    regions: ClassVar[Optional[list[str]]] = None
     host_kwargs: ClassVar[dict[str, Any]] = {
         "_scheduler": "nomad",
         "_scheduler_options": {
@@ -393,6 +394,7 @@ class App(BaseServable):
     max_concurrency: ClassVar[Optional[int]] = None
     concurrency_buffer: ClassVar[Optional[int]] = None
     concurrency_buffer_perc: ClassVar[Optional[int]] = None
+    scaling_delay: ClassVar[Optional[int]] = None
     max_multiplexing: ClassVar[Optional[int]] = None
     kind: ClassVar[Optional[str]] = None
     image: ClassVar[Optional[ContainerImage]] = None
@@ -436,21 +438,21 @@ class App(BaseServable):
         if cls.concurrency_buffer_perc is not None:
             cls.host_kwargs["concurrency_buffer_perc"] = cls.concurrency_buffer_perc
 
+        if cls.scaling_delay is not None:
+            cls.host_kwargs["scaling_delay"] = cls.scaling_delay
+
         if cls.max_multiplexing is not None:
             cls.host_kwargs["max_multiplexing"] = cls.max_multiplexing
 
         if cls.kind is not None:
             cls.host_kwargs["kind"] = cls.kind
-            if cls.kind == "container" and cls.app_files:
-                raise ValueError("app_files is not supported for container apps.")
 
         if cls.image is not None:
             cls.host_kwargs["image"] = cls.image
 
-        cls.app_name = getattr(cls, "app_name") or app_name
+        cls.host_kwargs["health_check_path"] = cls.get_health_check_endpoint()
 
-        if kwargs.get("kind") and cls.app_files:
-            raise ValueError("app_files is not supported for container apps.")
+        cls.app_name = getattr(cls, "app_name") or app_name
 
         if cls.__init__ is not App.__init__:
             raise ValueError(
@@ -474,6 +476,24 @@ class App(BaseServable):
             if (signature := getattr(endpoint, "route_signature", None))
         ]
 
+    @classmethod
+    def get_health_check_endpoint(cls) -> Optional[str]:
+        paths = [
+            signature.path
+            for _, endpoint in inspect.getmembers(cls, inspect.isfunction)
+            if (signature := getattr(endpoint, "route_signature", None))
+            and signature.is_health_check
+        ]
+        if len(paths) > 1:
+            raise ValueError(
+                f"Multiple health check endpoints found: {', '.join(paths)}. "
+                "An app can only have one health check endpoint."
+            )
+        elif len(paths) == 1:
+            return paths[0]
+        else:
+            return None
+
     def collect_routes(self) -> dict[RouteSignature, Callable[..., Any]]:
         return {
             signature: endpoint
@@ -483,6 +503,8 @@ class App(BaseServable):
 
     @asynccontextmanager
     async def lifespan(self, app: fastapi.FastAPI):
+        os.environ["FAL_RUNNER_STATE"] = "SETUP"
+
         # We want to not do any directory changes for container apps,
         # since we don't have explicit checks to see the kind of app
         # We check for app_files here and check kind and app_files earlier
@@ -491,9 +513,13 @@ class App(BaseServable):
             _include_app_files_path(self.local_file_path, self.app_files_context_dir)
         _print_python_packages()
         await _call_any_fn(self.setup)
+
+        os.environ["FAL_RUNNER_STATE"] = "RUNNING"
+
         try:
             yield
         finally:
+            os.environ["FAL_RUNNER_STATE"] = "STOPPING"
             await _call_any_fn(self.teardown)
 
     def health(self):
@@ -587,12 +613,18 @@ class App(BaseServable):
                 return await call_next(request)
 
             request_id = request.headers.get(REQUEST_ID_KEY)
-            if request_id is None:
+            request_endpoint = request.headers.get(REQUEST_ENDPOINT_KEY)
+
+            if request_id is None and request_endpoint is None:
                 return await call_next(request)
 
-            await _set_logger_labels(
-                {"fal_request_id": request_id}, channel=self.isolate_channel
-            )
+            labels_to_set = {}
+            if request_id:
+                labels_to_set["fal_request_id"] = request_id
+            if request_endpoint:
+                labels_to_set["fal_endpoint"] = request_endpoint
+
+            await _set_logger_labels(labels_to_set, channel=self.isolate_channel)
 
             async def _unset_at_end():
                 await _set_logger_labels({}, channel=self.isolate_channel)  # type: ignore
@@ -636,7 +668,7 @@ class App(BaseServable):
 
 
 def endpoint(
-    path: str, *, is_websocket: bool = False
+    path: str, *, is_websocket: bool = False, is_health_check: bool = False
 ) -> Callable[[EndpointT], EndpointT]:
     """Designate the decorated function as an application endpoint."""
 
@@ -646,7 +678,11 @@ def endpoint(
                 f"Can't set multiple routes for the same function: {callable.__name__}"
             )
 
-        callable.route_signature = RouteSignature(path=path, is_websocket=is_websocket)  # type: ignore
+        callable.route_signature = RouteSignature(  # type: ignore
+            path=path,
+            is_websocket=is_websocket,
+            is_health_check=is_health_check,
+        )
         return callable
 
     return marker_fn

fal/cli/_utils.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import copy
 from typing import Any, Optional
 
 from fal.project import find_project_root, find_pyproject_toml, parse_pyproject_toml
@@ -22,7 +23,13 @@ def is_app_name(app_ref: tuple[str, str | None]) -> bool:
 
 def get_app_data_from_toml(
     app_name,
-) -> tuple[str, Optional[AuthModeLiteral], Optional[DeploymentStrategyLiteral], bool]:
+) -> tuple[
+    str,
+    Optional[AuthModeLiteral],
+    Optional[DeploymentStrategyLiteral],
+    bool,
+    Optional[str],
+]:
     toml_path = find_pyproject_toml()
 
     if toml_path is None:
@@ -32,7 +39,7 @@ def get_app_data_from_toml(
     apps = fal_data.get("apps", {})
 
     try:
-        app_data: dict[str, Any] = apps[app_name]
+        app_data: dict[str, Any] = copy.deepcopy(apps[app_name])
     except KeyError:
         raise ValueError(f"App {app_name} not found in pyproject.toml")
 
@@ -49,6 +56,7 @@ def get_app_data_from_toml(
     app_deployment_strategy: Optional[DeploymentStrategyLiteral] = app_data.pop(
         "deployment_strategy", None
     )
+    app_team: Optional[str] = app_data.pop("team", None)
 
     app_reset_scale: bool
     if "no_scale" in app_data:
@@ -62,4 +70,4 @@ def get_app_data_from_toml(
     if len(app_data) > 0:
         raise ValueError(f"Found unexpected keys in pyproject.toml: {app_data}")
 
-    return app_ref, app_auth, app_deployment_strategy, app_reset_scale
+    return app_ref, app_auth, app_deployment_strategy, app_reset_scale, app_team

fal/cli/api.py

@@ -2,8 +2,6 @@ import re
 
 import rich
 
-import fal.apps
-
 # = or := only
 KV_SPLIT_RE = re.compile(r"(=|:=)")
 
@@ -24,6 +22,8 @@ def _api(args):
 
 
 def stream_run(model_id: str, params: dict):
+    import fal.apps
+
     res = fal.apps.stream(model_id, params)  # type: ignore
     for line in res:
         if isinstance(line, str):
@@ -41,6 +41,8 @@ def queue_run(model_id: str, params: dict):
     from rich.panel import Panel
     from rich.text import Text
 
+    import fal.apps
+
     handle = fal.apps.submit(model_id, params)  # type: ignore
     logs = []  # type: ignore
 

fal/cli/apps.py

@@ -14,6 +14,12 @@ from .parser import FalClientParser, SinceAction, get_output_parser
 if TYPE_CHECKING:
     from fal.sdk import AliasInfo, ApplicationInfo
 
+CODE_SPECIFIC_SCALING_PARAMS = [
+    "max_multiplexing",
+    "startup_timeout",
+    "machine_types",
+]
+
 
 def _apps_table(apps: list[AliasInfo]):
     from rich.table import Table
@@ -25,6 +31,7 @@ def _apps_table(apps: list[AliasInfo]):
     table.add_column("Min Concurrency")
     table.add_column("Max Concurrency")
     table.add_column("Concurrency Buffer")
+    table.add_column("Scaling Delay")
     table.add_column("Max Multiplexing")
     table.add_column("Keep Alive")
     table.add_column("Request Timeout")
@@ -48,6 +55,7 @@ def _apps_table(apps: list[AliasInfo]):
             str(app.min_concurrency),
             str(app.max_concurrency),
             concurrency_buffer_str,
+            str(app.scaling_delay),
             str(app.max_multiplexing),
             str(app.keep_alive),
             str(app.request_timeout),
@@ -169,6 +177,7 @@ def _scale(args):
         and args.min_concurrency is None
         and args.concurrency_buffer is None
         and args.concurrency_buffer_perc is None
+        and args.scaling_delay is None
         and args.request_timeout is None
         and args.startup_timeout is None
         and args.machine_types is None
@@ -185,6 +194,7 @@ def _scale(args):
         min_concurrency=args.min_concurrency,
         concurrency_buffer=args.concurrency_buffer,
         concurrency_buffer_perc=args.concurrency_buffer_perc,
+        scaling_delay=args.scaling_delay,
         request_timeout=args.request_timeout,
         startup_timeout=args.startup_timeout,
         machine_types=args.machine_types,
@@ -194,6 +204,18 @@ def _scale(args):
 
     args.console.print(table)
 
+    code_specific_changes = set()
+    for param in CODE_SPECIFIC_SCALING_PARAMS:
+        if getattr(args, param) is not None:
+            code_specific_changes.add(f"[bold]{param}[/bold]")
+
+    if len(code_specific_changes) > 0:
+        args.console.print(
+            "[bold yellow]Note:[/bold yellow] Please be aware that "
+            f"{', '.join(code_specific_changes)} will be reset on the next deployment. "
+            "See https://docs.fal.ai/serverless/deployment-operations/scale-your-application#code-specific-settings-reset-on-deploy for details."  # noqa: E501
+        )
+
 
 def _add_scale_parser(subparsers, parents):
     scale_help = "Scale application."
@@ -237,6 +259,11 @@ def _add_scale_parser(subparsers, parents):
         type=int,
         help="Concurrency buffer %",
     )
+    parser.add_argument(
+        "--scaling-delay",
+        type=int,
+        help="Scaling delay (seconds).",
+    )
     parser.add_argument(
         "--request-timeout",
         type=int,
@@ -262,6 +289,32 @@ def _add_scale_parser(subparsers, parents):
     parser.set_defaults(func=_scale)
 
 
+def _rollout(args):
+    client = SyncServerlessClient(host=args.host, team=args.team)
+    client.apps.rollout(args.app_name, force=args.force)
+    args.console.log(f"Rolled out application {args.app_name}")
+
+
+def _add_rollout_parser(subparsers, parents):
+    rollout_help = "Rollout application."
+    parser = subparsers.add_parser(
+        "rollout",
+        description=rollout_help,
+        help=rollout_help,
+        parents=parents,
+    )
+    parser.add_argument(
+        "app_name",
+        help="Application name.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force rollout.",
+    )
+    parser.set_defaults(func=_rollout)
+
+
 def _set_rev(args):
     client = get_client(args.host, args.team)
     with client.connect() as connection:
@@ -348,14 +401,14 @@ def _add_runners_parser(subparsers, parents):
         action=SinceAction,
         limit="1 day",
         help=(
-            "Show dead runners since the given time. "
+            "Show terminated runners since the given time. "
             "Accepts 'now', relative like '30m', '1h', '1d', "
             "or an ISO timestamp. Max 24 hours."
         ),
     )
     parser.add_argument(
         "--state",
-        choices=["all", "running", "pending", "setup", "dead"],
+        choices=["all", "running", "pending", "setup", "terminated"],
         nargs="+",
         default=None,
         help=("Filter by runner state(s). Choose one or more, or 'all'(default)."),
@@ -431,6 +484,7 @@ def add_parser(main_subparsers, parents):
     _add_list_rev_parser(subparsers, parents)
     _add_set_rev_parser(subparsers, parents)
     _add_scale_parser(subparsers, parents)
+    _add_rollout_parser(subparsers, parents)
     _add_runners_parser(subparsers, parents)
     _add_delete_parser(subparsers, parents)
     _add_delete_rev_parser(subparsers, parents)

fal/cli/deploy.py

@@ -7,9 +7,23 @@ from .parser import FalClientParser, RefAction, get_output_parser
 
 
 def _deploy(args):
-    client = SyncServerlessClient(host=args.host, team=args.team)
+    from ._utils import get_app_data_from_toml, is_app_name
+
+    team = args.team
+    app_ref = args.app_ref
+
+    # If the app_ref is an app name, get team from pyproject.toml
+    if app_ref and is_app_name(app_ref):
+        try:
+            *_, toml_team = get_app_data_from_toml(app_ref[0])
+            team = team or toml_team
+        except (ValueError, FileNotFoundError):
+            # If we can't find the app in pyproject.toml, team remains None
+            pass
+
+    client = SyncServerlessClient(host=args.host, team=team)
     res = client.deploy(
-        args.app_ref,
+        app_ref,
         app_name=args.app_name,
         auth=args.auth,
         strategy=args.strategy,
@@ -86,7 +100,7 @@ def add_parser(main_subparsers, parents):
             "command will look for a pyproject.toml file with a [tool.fal.apps] "
             "section and deploy the application specified with the provided app name.\n"
             "File path example: path/to/myfile.py::MyApp\n"
-            "App name example: my-app\n"
+            "App name example: my-app (configure team in pyproject.toml)\n"
         ),
     )
 

fal/cli/files.py

@@ -1,52 +1,44 @@
+from typing import TYPE_CHECKING
+
 from .parser import FalClientParser
 
+if TYPE_CHECKING:
+    from fal.files import FalFileSystem
 
-def _list(args):
-    import posixpath
 
+def _get_fs(args) -> "FalFileSystem":
     from fal.files import FalFileSystem
 
-    fs = FalFileSystem()
+    return FalFileSystem(host=args.host, team=args.team)
+
 
-    for entry in fs.ls(args.path, detail=True):
+def _list(args):
+    import posixpath
+
+    for entry in _get_fs(args).ls(args.path, detail=True):
         name = posixpath.basename(entry["name"])
         color = "blue" if entry["type"] == "directory" else "default"
         args.console.print(f"[{color}]{name}[/{color}]")
 
 
 def _download(args):
-    from fal.files import FalFileSystem
-
-    fs = FalFileSystem()
-    fs.get(args.remote_path, args.local_path, recursive=True)
+    _get_fs(args).get(args.remote_path, args.local_path, recursive=True)
 
 
 def _upload(args):
-    from fal.files import FalFileSystem
-
-    fs = FalFileSystem()
-    fs.put(args.local_path, args.remote_path, recursive=True)
+    _get_fs(args).put(args.local_path, args.remote_path, recursive=True)
 
 
 def _upload_url(args):
-    from fal.files import FalFileSystem
-
-    fs = FalFileSystem()
-    fs.put_file_from_url(args.url, args.remote_path)
+    _get_fs(args).put_file_from_url(args.url, args.remote_path)
 
 
 def _mv(args):
-    from fal.files import FalFileSystem
-
-    fs = FalFileSystem()
-    fs.mv(args.source, args.destination)
+    _get_fs(args).mv(args.source, args.destination)
 
 
 def _rm(args):
-    from fal.files import FalFileSystem
-
-    fs = FalFileSystem()
-    fs.rm(args.path)
+    _get_fs(args).rm(args.path)
 
 
 def add_parser(main_subparsers, parents):

fal/cli/keys.py

@@ -1,21 +1,20 @@
+from fal.api.client import SyncServerlessClient
 from fal.sdk import KeyScope
 
-from ._utils import get_client
 from .parser import FalClientParser
 
 
 def _create(args):
-    client = get_client(args.host, args.team)
-    with client.connect() as connection:
-        parsed_scope = KeyScope(args.scope)
-        result = connection.create_user_key(parsed_scope, args.desc)
-        args.console.print(
-            f"Generated key id and key secret, with the scope `{args.scope}`.\n"
-            "This is the only time the secret will be visible.\n"
-            "You will need to generate a new key pair if you lose access to this "
-            "secret."
-        )
-        args.console.print(f"FAL_KEY='{result[1]}:{result[0]}'")
+    client = SyncServerlessClient(host=args.host, team=args.team)
+    parsed_scope = KeyScope(args.scope)
+    key_id, key_secret = client.keys.create(scope=parsed_scope, description=args.desc)
+    args.console.print(
+        f"Generated key id and key secret, with the scope `{args.scope}`.\n"
+        "This is the only time the secret will be visible.\n"
+        "You will need to generate a new key pair if you lose access to this "
+        "secret."
+    )
+    args.console.print(f"FAL_KEY='{key_id}:{key_secret}'")
 
 
 def _add_create_parser(subparsers, parents):
@@ -42,41 +41,40 @@ def _add_create_parser(subparsers, parents):
 def _list(args):
     import json
 
-    client = get_client(args.host, args.team)
-    with client.connect() as connection:
-        keys = connection.list_user_keys()
-
-        if args.output == "json":
-            json_keys = [
-                {
-                    "key_id": key.key_id,
-                    "created_at": str(key.created_at),
-                    "scope": str(key.scope.value),
-                    "description": key.alias,
-                }
-                for key in keys
-            ]
-            args.console.print(json.dumps({"keys": json_keys}))
-        elif args.output == "pretty":
-            from rich.table import Table
-
-            table = Table()
-            table.add_column("Key ID")
-            table.add_column("Created At")
-            table.add_column("Scope")
-            table.add_column("Description")
-
-            for key in keys:
-                table.add_row(
-                    key.key_id,
-                    str(key.created_at),
-                    str(key.scope.value),
-                    key.alias,
-                )
-
-            args.console.print(table)
-        else:
-            raise AssertionError(f"Invalid output format: {args.output}")
+    client = SyncServerlessClient(host=args.host, team=args.team)
+    keys = client.keys.list()
+
+    if args.output == "json":
+        json_keys = [
+            {
+                "key_id": key.key_id,
+                "created_at": str(key.created_at),
+                "scope": str(key.scope.value),
+                "description": key.alias,
+            }
+            for key in keys
+        ]
+        args.console.print(json.dumps({"keys": json_keys}))
+    elif args.output == "pretty":
+        from rich.table import Table
+
+        table = Table()
+        table.add_column("Key ID")
+        table.add_column("Created At")
+        table.add_column("Scope")
+        table.add_column("Description")
+
+        for key in keys:
+            table.add_row(
+                key.key_id,
+                str(key.created_at),
+                str(key.scope.value),
+                key.alias,
+            )
+
+        args.console.print(table)
+    else:
+        raise AssertionError(f"Invalid output format: {args.output}")
 
 
 def _add_list_parser(subparsers, parents):
@@ -93,9 +91,8 @@ def _add_list_parser(subparsers, parents):
 
 
 def _revoke(args):
-    client = get_client(args.host, args.team)
-    with client.connect() as connection:
-        connection.revoke_user_key(args.key_id)
+    client = SyncServerlessClient(host=args.host, team=args.team)
+    client.keys.revoke(args.key_id)
 
 
 def _add_revoke_parser(subparsers, parents):

fal/cli/queue.py

@@ -5,20 +5,20 @@ from http import HTTPStatus
 
 import httpx
 
-from fal.rest_client import REST_CLIENT
-
 from .parser import FalClientParser, get_output_parser
 
 
 def _queue_size(args):
+    from fal.api.client import SyncServerlessClient
     from fal.api.deploy import _get_user
 
-    user = _get_user()
+    client = SyncServerlessClient(host=args.host, team=args.team)._create_rest_client()
+    user = _get_user(client)
 
-    url = f"{REST_CLIENT.base_url}/applications/{user.username}/{args.app_name}/queue"
-    headers = REST_CLIENT.get_headers()
+    url = f"{client.base_url}/applications/{user.username}/{args.app_name}/queue"
+    headers = client.get_headers()
 
-    with httpx.Client(base_url=REST_CLIENT.base_url, headers=headers, timeout=300) as c:
+    with httpx.Client(base_url=client.base_url, headers=headers, timeout=300) as c:
         resp = c.get(url)
 
     if resp.status_code != HTTPStatus.OK:
@@ -38,14 +38,16 @@ def _queue_size(args):
 
 
 def _queue_flush(args):
+    from fal.api.client import SyncServerlessClient
     from fal.api.deploy import _get_user
 
-    user = _get_user()
+    client = SyncServerlessClient(host=args.host, team=args.team)._create_rest_client()
+    user = _get_user(client)
 
-    url = f"{REST_CLIENT.base_url}/applications/{user.username}/{args.app_name}/queue"
-    headers = REST_CLIENT.get_headers()
+    url = f"{client.base_url}/applications/{user.username}/{args.app_name}/queue"
+    headers = client.get_headers()
 
-    with httpx.Client(base_url=REST_CLIENT.base_url, headers=headers, timeout=300) as c:
+    with httpx.Client(base_url=client.base_url, headers=headers, timeout=300) as c:
         resp = c.delete(url)
 
     if resp.status_code != HTTPStatus.OK:

fal/cli/run.py

@@ -8,16 +8,20 @@ def _run(args):
     from fal.api.client import SyncServerlessClient
     from fal.utils import load_function_from
 
-    if is_app_name(args.func_ref):
-        app_name = args.func_ref[0]
-        app_ref, *_ = get_app_data_from_toml(app_name)
+    team = args.team
+    func_ref = args.func_ref
+
+    if is_app_name(func_ref):
+        app_name = func_ref[0]
+        app_ref, *_, toml_team = get_app_data_from_toml(app_name)
+        team = team or toml_team
         file_path, func_name = RefAction.split_ref(app_ref)
     else:
-        file_path, func_name = args.func_ref
+        file_path, func_name = func_ref
         # Turn relative path into absolute path for files
         file_path = str(Path(file_path).absolute())
 
-    client = SyncServerlessClient(host=args.host, team=args.team)
+    client = SyncServerlessClient(host=args.host, team=team)
     host = client._create_host(local_file_path=file_path)
 
     loaded = load_function_from(host, file_path, func_name)
@@ -30,7 +34,7 @@ def _run(args):
 
 def add_parser(main_subparsers, parents):
     run_help = "Run fal function."
-    epilog = "Examples:\n" "  fal run path/to/myfile.py::myfunc"
+    epilog = "Examples:\n" "  fal run path/to/myfile.py::myfunc\n" "  fal run my-app\n"
     parser = main_subparsers.add_parser(
         "run",
         description=run_help,
@@ -41,6 +45,6 @@ def add_parser(main_subparsers, parents):
     parser.add_argument(
         "func_ref",
         action=RefAction,
-        help="Function reference.",
+        help="Function reference. Configure team in pyproject.toml for app names.",
     )
     parser.set_defaults(func=_run)