fal 1.41.1__py3-none-any.whl → 1.43.0__py3-none-any.whl

fal/_fal_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.41.1'
-__version_tuple__ = version_tuple = (1, 41, 1)
+__version__ = version = '1.43.0'
+__version_tuple__ = version_tuple = (1, 43, 0)
 
 __commit_id__ = commit_id = None

fal/api.py

@@ -21,6 +21,7 @@ from typing import (
     Iterator,
     Literal,
     NamedTuple,
+    Optional,
     TypeVar,
     cast,
     overload,
@@ -53,10 +54,13 @@ from fal.exceptions._cuda import _is_cuda_oom_exception
 from fal.logging.isolate import IsolateLogPrinter
 from fal.sdk import (
     FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER,
+    FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER_PERC,
     FAL_SERVERLESS_DEFAULT_KEEP_ALIVE,
     FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
     FAL_SERVERLESS_DEFAULT_MIN_CONCURRENCY,
+    AuthModeLiteral,
     Credentials,
+    DeploymentStrategyLiteral,
     FalServerlessClient,
     FalServerlessConnection,
     HostedRunState,
@@ -424,6 +428,7 @@ class FalServerlessHost(Host):
             "max_concurrency",
             "min_concurrency",
             "concurrency_buffer",
+            "concurrency_buffer_perc",
             "max_multiplexing",
             "setup_function",
             "metadata",
@@ -465,12 +470,13 @@ class FalServerlessHost(Host):
         self,
         func: Callable[ArgsT, ReturnT],
         options: Options,
-        application_name: str | None = None,
-        application_auth_mode: Literal["public", "shared", "private"] | None = None,
-        metadata: dict[str, Any] | None = None,
-        deployment_strategy: Literal["recreate", "rolling"] = "recreate",
+        *,
+        application_name: Optional[str] = None,
+        application_auth_mode: Optional[AuthModeLiteral] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        deployment_strategy: DeploymentStrategyLiteral,
         scale: bool = True,
-    ) -> str | None:
+    ) -> Optional[str]:
         from isolate.backends.common import active_python
 
         environment_options = options.environment.copy()
@@ -487,6 +493,7 @@ class FalServerlessHost(Host):
         max_concurrency = options.host.get("max_concurrency")
         min_concurrency = options.host.get("min_concurrency")
         concurrency_buffer = options.host.get("concurrency_buffer")
+        concurrency_buffer_perc = options.host.get("concurrency_buffer_perc")
         max_multiplexing = options.host.get("max_multiplexing")
         exposed_port = options.get_exposed_port()
         request_timeout = options.host.get("request_timeout")
@@ -503,6 +510,7 @@ class FalServerlessHost(Host):
             max_concurrency=max_concurrency,
             min_concurrency=min_concurrency,
             concurrency_buffer=concurrency_buffer,
+            concurrency_buffer_perc=concurrency_buffer_perc,
             request_timeout=request_timeout,
             startup_timeout=startup_timeout,
         )
@@ -560,6 +568,7 @@ class FalServerlessHost(Host):
         max_concurrency = options.host.get("max_concurrency")
         min_concurrency = options.host.get("min_concurrency")
         concurrency_buffer = options.host.get("concurrency_buffer")
+        concurrency_buffer_perc = options.host.get("concurrency_buffer_perc")
         max_multiplexing = options.host.get("max_multiplexing")
         base_image = options.host.get("_base_image", None)
         scheduler = options.host.get("_scheduler", None)
@@ -580,6 +589,7 @@ class FalServerlessHost(Host):
             max_concurrency=max_concurrency,
             min_concurrency=min_concurrency,
             concurrency_buffer=concurrency_buffer,
+            concurrency_buffer_perc=concurrency_buffer_perc,
             request_timeout=request_timeout,
             startup_timeout=startup_timeout,
         )
@@ -770,6 +780,7 @@ def function(
     max_multiplexing: int = FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
     min_concurrency: int = FAL_SERVERLESS_DEFAULT_MIN_CONCURRENCY,
     concurrency_buffer: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER,
+    concurrency_buffer_perc: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER_PERC,
     request_timeout: int | None = None,
     startup_timeout: int | None = None,
     setup_function: Callable[..., None] | None = None,
@@ -800,6 +811,7 @@ def function(
     max_multiplexing: int = FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
     min_concurrency: int = FAL_SERVERLESS_DEFAULT_MIN_CONCURRENCY,
     concurrency_buffer: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER,
+    concurrency_buffer_perc: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER_PERC,
     request_timeout: int | None = None,
     startup_timeout: int | None = None,
     setup_function: Callable[..., None] | None = None,
@@ -882,6 +894,7 @@ def function(
     max_multiplexing: int = FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
     min_concurrency: int = FAL_SERVERLESS_DEFAULT_MIN_CONCURRENCY,
     concurrency_buffer: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER,
+    concurrency_buffer_perc: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER_PERC,
     request_timeout: int | None = None,
     startup_timeout: int | None = None,
     setup_function: Callable[..., None] | None = None,
@@ -917,6 +930,7 @@ def function(
     max_multiplexing: int = FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
     min_concurrency: int = FAL_SERVERLESS_DEFAULT_MIN_CONCURRENCY,
     concurrency_buffer: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER,
+    concurrency_buffer_perc: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER_PERC,
     request_timeout: int | None = None,
     startup_timeout: int | None = None,
     setup_function: Callable[..., None] | None = None,
@@ -946,6 +960,7 @@ def function(
     max_multiplexing: int = FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
     min_concurrency: int = FAL_SERVERLESS_DEFAULT_MIN_CONCURRENCY,
     concurrency_buffer: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER,
+    concurrency_buffer_perc: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER_PERC,
     request_timeout: int | None = None,
     startup_timeout: int | None = None,
     setup_function: Callable[..., None] | None = None,
@@ -975,6 +990,7 @@ def function(
     max_multiplexing: int = FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
     min_concurrency: int = FAL_SERVERLESS_DEFAULT_MIN_CONCURRENCY,
     concurrency_buffer: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER,
+    concurrency_buffer_perc: int = FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER_PERC,
     request_timeout: int | None = None,
     startup_timeout: int | None = None,
     setup_function: Callable[..., None] | None = None,

fal/app.py

@@ -11,7 +11,7 @@ import time
 import typing
 from contextlib import asynccontextmanager, contextmanager
 from dataclasses import dataclass
-from typing import Any, Callable, ClassVar, Literal, TypeVar
+from typing import Any, Callable, ClassVar, Optional, TypeVar
 
 import fastapi
 import grpc.aio as async_grpc
@@ -29,6 +29,7 @@ from fal.api import (
 )
 from fal.exceptions import FalServerlessException, RequestCancelledException
 from fal.logging import get_logger
+from fal.sdk import AuthModeLiteral
 from fal.toolkit.file import request_lifecycle_preference
 from fal.toolkit.file.providers.fal import LIFECYCLE_PREFERENCE
 
@@ -311,7 +312,7 @@ class App(BaseServable):
         "keep_alive": 60,
     }
     app_name: ClassVar[str]
-    app_auth: ClassVar[Literal["private", "public", "shared", None]] = None
+    app_auth: ClassVar[Optional[AuthModeLiteral]] = None
     request_timeout: ClassVar[int | None] = None
     startup_timeout: ClassVar[int | None] = None
 

fal/cli/_utils.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
+from typing import Any, Optional
+
 from fal.project import find_project_root, find_pyproject_toml, parse_pyproject_toml
+from fal.sdk import AuthModeLiteral, DeploymentStrategyLiteral
 
 
 def get_client(host: str, team: str | None = None):
-    from fal.sdk import FalServerlessClient, get_default_credentials
+    from fal.sdk import FalServerlessClient, get_default_credentials  # noqa: PLC0415
 
     credentials = get_default_credentials(team=team)
     return FalServerlessClient(host, credentials)
@@ -17,7 +20,9 @@ def is_app_name(app_ref: tuple[str, str | None]) -> bool:
     return is_single_file and not is_python_file
 
 
-def get_app_data_from_toml(app_name):
+def get_app_data_from_toml(
+    app_name,
+) -> tuple[str, Optional[AuthModeLiteral], Optional[DeploymentStrategyLiteral], bool]:
     toml_path = find_pyproject_toml()
 
     if toml_path is None:
@@ -27,12 +32,12 @@ def get_app_data_from_toml(app_name):
     apps = fal_data.get("apps", {})
 
     try:
-        app_data = apps[app_name]
+        app_data: dict[str, Any] = apps[app_name]
     except KeyError:
         raise ValueError(f"App {app_name} not found in pyproject.toml")
 
     try:
-        app_ref = app_data.pop("ref")
+        app_ref: str = app_data.pop("ref")
     except KeyError:
         raise ValueError(f"App {app_name} does not have a ref key in pyproject.toml")
 
@@ -40,12 +45,15 @@ def get_app_data_from_toml(app_name):
     project_root, _ = find_project_root(None)
     app_ref = str(project_root / app_ref)
 
-    app_auth = app_data.pop("auth", "private")
-    app_deployment_strategy = app_data.pop("deployment_strategy", "recreate")
+    app_auth: Optional[AuthModeLiteral] = app_data.pop("auth", None)
+    app_deployment_strategy: Optional[DeploymentStrategyLiteral] = app_data.pop(
+        "deployment_strategy", None
+    )
 
+    app_reset_scale: bool
     if "no_scale" in app_data:
         # Deprecated
-        app_no_scale = app_data.pop("no_scale")
+        app_no_scale: bool = app_data.pop("no_scale")
         print("[WARNING] no_scale is deprecated, use app_scale_settings instead")
         app_reset_scale = not app_no_scale
     else:

fal/cli/apps.py

@@ -33,13 +33,20 @@ def _apps_table(apps: list[AliasInfo]):
     table.add_column("Regions")
 
     for app in apps:
+        if app.concurrency_buffer_perc > 0:
+            concurrency_buffer_str = (
+                f"{app.concurrency_buffer_perc}%, min {app.concurrency_buffer}"
+            )
+        else:
+            concurrency_buffer_str = str(app.concurrency_buffer)
+
         table.add_row(
             app.alias,
             app.revision,
             app.auth_mode,
             str(app.min_concurrency),
             str(app.max_concurrency),
-            str(app.concurrency_buffer),
+            concurrency_buffer_str,
             str(app.max_multiplexing),
             str(app.keep_alive),
             str(app.request_timeout),
@@ -165,6 +172,7 @@ def _scale(args):
             and args.max_concurrency is None
             and args.min_concurrency is None
             and args.concurrency_buffer is None
+            and args.concurrency_buffer_perc is None
             and args.request_timeout is None
             and args.startup_timeout is None
             and args.machine_types is None
@@ -180,6 +188,7 @@ def _scale(args):
             max_concurrency=args.max_concurrency,
             min_concurrency=args.min_concurrency,
             concurrency_buffer=args.concurrency_buffer,
+            concurrency_buffer_perc=args.concurrency_buffer_perc,
             request_timeout=args.request_timeout,
             startup_timeout=args.startup_timeout,
             machine_types=args.machine_types,
@@ -225,7 +234,12 @@ def _add_scale_parser(subparsers, parents):
     parser.add_argument(
         "--concurrency-buffer",
         type=int,
-        help="Concurrency buffer",
+        help="Concurrency buffer (min)",
+    )
+    parser.add_argument(
+        "--concurrency-buffer-perc",
+        type=int,
+        help="Concurrency buffer %",
     )
     parser.add_argument(
         "--request-timeout",

fal/cli/deploy.py

@@ -2,7 +2,9 @@ import argparse
 import json
 from collections import namedtuple
 from pathlib import Path
-from typing import Literal, Optional, Tuple, Union
+from typing import Optional, Tuple, Union, cast
+
+from fal.sdk import AuthModeLiteral, DeploymentStrategyLiteral
 
 from ._utils import get_app_data_from_toml, is_app_name
 from .parser import FalClientParser, RefAction, get_output_parser
@@ -67,8 +69,8 @@ def _deploy_from_reference(
     app_ref: Tuple[Optional[Union[Path, str]], ...],
     app_name: str,
     args,
-    auth: Optional[Literal["public", "shared", "private"]],
-    deployment_strategy: Optional[Literal["recreate", "rolling"]],
+    auth: Optional[AuthModeLiteral],
+    deployment_strategy: Optional[DeploymentStrategyLiteral],
     scale: bool,
 ):
     from fal.api import FalServerlessError, FalServerlessHost
@@ -99,7 +101,7 @@ def _deploy_from_reference(
     isolated_function = loaded.function
     app_name = app_name or loaded.app_name  # type: ignore
     app_auth = auth or loaded.app_auth
-    deployment_strategy = deployment_strategy or "recreate"
+    deployment_strategy = deployment_strategy or "rolling"
 
     app_id = host.register(
         func=isolated_function.func,
@@ -172,10 +174,12 @@ def _deploy(args):
     # path/to/myfile.py::MyApp
     else:
         file_path, func_name = args.app_ref
-        app_name = args.app_name
-        app_auth = args.auth
-        app_deployment_strategy = args.strategy
-        app_scale_settings = args.app_scale_settings
+        app_name = cast(str, args.app_name)
+        # default to be set in the backend
+        app_auth = cast(Optional[AuthModeLiteral], args.auth)
+        # default comes from the CLI
+        app_deployment_strategy = cast(DeploymentStrategyLiteral, args.strategy)
+        app_scale_settings = cast(bool, args.app_scale_settings)
 
     _deploy_from_reference(
         (file_path, func_name),
@@ -251,7 +255,7 @@ def add_parser(main_subparsers, parents):
         "--strategy",
         choices=["recreate", "rolling"],
         help="Deployment strategy.",
-        default="recreate",
+        default="rolling",
     )
     parser.add_argument(
         "--no-scale",

fal/cli/parser.py

@@ -86,6 +86,37 @@ class SinceAction(argparse.Action):
 
         super().__init__(*args, **kwargs)
 
+        # If a default is provided as a string like "1h ago", parse it into a datetime
+        # so callers can rely on receiving a datetime even when the flag isn't passed.
+        default_value = getattr(self, "default", None)
+        if default_value is not None and default_value is not argparse.SUPPRESS:
+            if isinstance(default_value, str):
+                dt = self._parse_since(default_value)
+                if not dt:
+                    raise ValueError(
+                        f"Invalid 'default' value for SinceAction: {default_value!r}"
+                    )
+                if (
+                    self._limit
+                    and self._limit_dt is not None
+                    and dt < self._limit_dt - self.LIMIT_LEEWAY
+                ):
+                    raise ValueError(
+                        "Default since value is older than the allowed limit "
+                        f"{self._limit}."
+                    )
+                self.default = dt
+            elif isinstance(default_value, datetime):
+                if (
+                    self._limit
+                    and self._limit_dt is not None
+                    and default_value < self._limit_dt - self.LIMIT_LEEWAY
+                ):
+                    raise ValueError(
+                        "Default since value is older than the allowed limit "
+                        f"{self._limit}."
+                    )
+
     def __call__(self, parser, args, values, option_string=None):  # noqa: ARG002
         if values is None:
             setattr(args, self.dest, None)
@@ -102,7 +133,7 @@ class SinceAction(argparse.Action):
                 ),
             )
 
-        if self._limit_dt is not None:
+        if self._limit and self._limit_dt is not None:
             if dt < self._limit_dt - self.LIMIT_LEEWAY:
                 raise argparse.ArgumentError(
                     self,

fal/cli/runners.py

@@ -1,9 +1,18 @@
 from __future__ import annotations
 
 import json
-from datetime import timedelta
-from typing import List
-
+from collections import deque
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from http import HTTPStatus
+from typing import Iterator, List
+
+import httpx
+from httpx_sse import connect_sse
+from rich.console import Console
+from structlog.typing import EventDict
+
+from fal.rest_client import REST_CLIENT
 from fal.sdk import RunnerInfo, RunnerState
 
 from ._utils import get_client
@@ -198,6 +207,347 @@ def _add_list_parser(subparsers, parents):
     parser.set_defaults(func=_list)
 
 
+def _to_iso_naive(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).isoformat()
+
+
+def _parse_ts(ts: str) -> datetime:
+    # Support both 'Z' and offset formats
+    ts_norm = ts.replace("Z", "+00:00")
+    return datetime.fromisoformat(ts_norm)
+
+
+def _to_aware_utc(dt: datetime) -> datetime:
+    # Treat naive datetimes as UTC
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def _post_history(
+    client: httpx.Client,
+    base_params: dict[str, str],
+    since: datetime | None,
+    until: datetime | None,
+    page_size: int,
+) -> tuple[list, str | None]:
+    params: dict[str, str] = dict(base_params)
+    if since is not None:
+        params["since"] = _to_iso_naive(since)
+    if until is not None:
+        params["until"] = _to_iso_naive(until)
+    params["page_size"] = str(page_size)
+    resp = client.post("/logs/history", params=params)
+    if resp.status_code != HTTPStatus.OK:
+        try:
+            detail = resp.json().get("detail", resp.text)
+        except Exception:
+            detail = resp.text
+        raise RuntimeError(f"Failed to fetch logs history: {detail}")
+    data = resp.json()
+    items = data.get("items", []) if isinstance(data, dict) else []
+    next_until = data.get("next_until") if isinstance(data, dict) else None
+    if not isinstance(items, list):
+        raise RuntimeError("Unexpected logs history response format")
+    return items, next_until
+
+
+@dataclass
+class RestRunnerInfo:
+    started_at: datetime | None
+    ended_at: datetime | None
+
+
+def _get_runner_info(runner_id: str) -> RestRunnerInfo:
+    headers = REST_CLIENT.get_headers()
+    with httpx.Client(
+        base_url=REST_CLIENT.base_url, headers=headers, timeout=30
+    ) as client:
+        resp = client.get(f"/runners/{runner_id}")
+        if resp.status_code == HTTPStatus.NOT_FOUND:
+            raise RuntimeError(f"Runner {runner_id} not found")
+        if resp.status_code != HTTPStatus.OK:
+            raise RuntimeError(
+                f"Failed to fetch runner info: {resp.status_code} {resp.text}"
+            )
+        data = resp.json()
+        if not isinstance(data, dict):
+            raise RuntimeError(f"Unexpected runner info response format: {resp.text}")
+
+        start: datetime | None = None
+        end: datetime | None = None
+
+        started_at = data.get("started_at")
+        if started_at is not None:
+            try:
+                start = _to_aware_utc(_parse_ts(started_at))
+            except Exception:
+                start = None
+
+        ended_at = data.get("ended_at")
+        if ended_at is not None:
+            try:
+                end = _to_aware_utc(_parse_ts(ended_at))
+            except Exception:
+                end = None
+
+        return RestRunnerInfo(started_at=start, ended_at=end)
+
+
+def _stream_logs(
+    base_params: dict[str, str], since: datetime | None, until: datetime | None
+) -> Iterator[dict]:
+    headers = REST_CLIENT.get_headers()
+    params: dict[str, str] = base_params.copy()
+    if since is not None:
+        params["since"] = _to_iso_naive(since)
+    if until is not None:
+        params["until"] = _to_iso_naive(until)
+    with httpx.Client(
+        base_url=REST_CLIENT.base_url,
+        headers=headers,
+        timeout=None,
+        follow_redirects=True,
+    ) as client:
+        with connect_sse(
+            client,
+            method="POST",
+            url="/logs/stream",
+            params=params,
+            headers={"Accept": "text/event-stream"},
+        ) as event_source:
+            for sse in event_source.iter_sse():
+                if not sse.data:
+                    continue
+                if sse.event == "error":
+                    raise RuntimeError(f"Error streaming logs: {sse.data}")
+                try:
+                    yield json.loads(sse.data)
+                except Exception:
+                    continue
+
+
+DEFAULT_PAGE_SIZE = 1000
+
+
+def _iter_logs(
+    base_params: dict[str, str], start: datetime | None, end: datetime | None
+) -> Iterator[dict]:
+    headers = REST_CLIENT.get_headers()
+    with httpx.Client(
+        base_url=REST_CLIENT.base_url,
+        headers=headers,
+        timeout=300,
+        follow_redirects=True,
+    ) as client:
+        cursor_until = end
+        while True:
+            items, next_until = _post_history(
+                client, base_params, start, cursor_until, DEFAULT_PAGE_SIZE
+            )
+
+            yield from items
+
+            if not next_until:
+                break
+
+            new_until_dt = _to_aware_utc(_parse_ts(next_until))
+            if start is not None and new_until_dt <= start:
+                break
+            cursor_until = new_until_dt
+
+
+def _get_logs(
+    params: dict[str, str],
+    since: datetime | None,
+    until: datetime | None,
+    lines_count: int | None,
+    *,
+    oldest: bool = False,
+) -> Iterator[dict]:
+    if lines_count is None:
+        yield from _iter_logs(params, since, until)
+        return
+
+    if oldest:
+        produced = 0
+        for log in _iter_logs(params, since, until):
+            if produced >= lines_count:
+                break
+            produced += 1
+            yield log
+        return
+
+    # newest tail: collect into a fixed-size deque, then yield
+    tail: deque[dict] = deque(maxlen=lines_count)
+    for log in _iter_logs(params, since, until):
+        tail.append(log)
+    for log in tail:
+        yield log
+
+
+class LogPrinter:
+    def __init__(self, console: Console) -> None:
+        from structlog.dev import ConsoleRenderer
+
+        from fal.logging.style import LEVEL_STYLES
+
+        self._console = console
+        self._renderer = ConsoleRenderer(level_styles=LEVEL_STYLES)
+
+    def _render_log(self, log: dict) -> str:
+        ts_str: str = log["timestamp"]
+        timestamp = _to_aware_utc(_parse_ts(ts_str))
+        local_ts = timestamp.astimezone()
+        tz_offset = local_ts.strftime("%z")
+        # Insert ':' into offset for readability, e.g. +0300 -> +03:00
+        if tz_offset and len(tz_offset) == 5:
+            tz_offset = tz_offset[:3] + ":" + tz_offset[3:]
+
+        event: EventDict = {
+            "event": log.get("message", ""),
+            "level": str(log.get("level", "")).upper(),
+            "timestamp": f"{local_ts.strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]}{tz_offset}",
+        }
+        return self._renderer(logger={}, name=event["level"], event_dict=event)
+
+    def print(self, log: dict) -> None:
+        self._console.print(self._render_log(log), highlight=False)
+
+
+DEFAULT_STREAM_SINCE = timedelta(minutes=1)
+
+
+def _logs(args):
+    params: dict[str, str] = {"job_id": args.id}
+    if getattr(args, "search", None) is not None:
+        params["search"] = args.search
+
+    runner_info = _get_runner_info(args.id)
+    follow: bool = getattr(args, "follow", False)
+    since = getattr(args, "since", None)
+    if follow:
+        since = since or (datetime.now(timezone.utc) - DEFAULT_STREAM_SINCE)
+    else:
+        since = since or runner_info.started_at
+    until = getattr(args, "until", None) or runner_info.ended_at
+
+    # Normalize to aware UTC for comparisons
+    if since is not None:
+        since = _to_aware_utc(since)
+    if until is not None:
+        until = _to_aware_utc(until)
+
+    # Sanity limiters: clamp within runner lifetime when known
+    if runner_info.started_at is not None:
+        if since is not None and since < runner_info.started_at:
+            since = runner_info.started_at
+        if until is not None and until < runner_info.started_at:
+            until = runner_info.started_at
+    if runner_info.ended_at is not None:
+        if since is not None and since > runner_info.ended_at:
+            since = runner_info.ended_at
+        if until is not None and until > runner_info.ended_at:
+            until = runner_info.ended_at
+
+    # Ensure ordering if both are present
+    if since is not None and until is not None and until < since:
+        since, until = until, since
+
+    lines_arg = getattr(args, "lines", None)
+    lines_count: int | None = None
+    lines_oldest = False
+    if lines_arg is not None:
+        if lines_arg.startswith("+"):
+            lines_str = lines_arg[1:]
+            lines_oldest = True
+        else:
+            lines_str = lines_arg
+        try:
+            lines_count = int(lines_str)
+        except ValueError:
+            args.parser.error("Invalid -n|--lines value. Use an integer or +integer.")
+
+    if follow:
+        logs_gen = _stream_logs(params, since, until)
+    else:
+        logs_gen = _get_logs(params, since, until, lines_count, oldest=lines_oldest)
+
+    printer = LogPrinter(args.console)
+
+    if follow:
+        for log in logs_gen:
+            if args.output == "json":
+                args.console.print(json.dumps(log))
+            else:
+                printer.print(log)
+        return
+
+    if args.output == "json":
+        args.console.print(json.dumps({"logs": list(logs_gen)}))
+    else:
+        for log in reversed(list(logs_gen)):
+            printer.print(log)
+
+
+def _add_logs_parser(subparsers, parents):
+    logs_help = "Show logs for a runner."
+    parser = subparsers.add_parser(
+        "logs",
+        aliases=["log"],
+        description=logs_help,
+        help=logs_help,
+        parents=[*parents, get_output_parser()],
+    )
+    parser.add_argument(
+        "id",
+        help="Runner ID.",
+    )
+    parser.add_argument(
+        "--search",
+        default=None,
+        help="Search for string in logs.",
+    )
+    parser.add_argument(
+        "--since",
+        default=None,
+        action=SinceAction,
+        help=(
+            "Show logs since the given time. "
+            "Accepts 'now', relative like '30m', '1h', or an ISO timestamp. "
+            "Defaults to runner start time or to '1m ago' in --follow mode."
+        ),
+    )
+    parser.add_argument(
+        "--until",
+        default=None,
+        action=SinceAction,
+        help=(
+            "Show logs until the given time. "
+            "Accepts 'now', relative like '30m', '1h', or an ISO timestamp. "
+            "Defaults to runner finish time or 'now' if it is still running."
+        ),
+    )
+    parser.add_argument(
+        "--follow",
+        "-f",
+        action="store_true",
+        help="Follow logs live. If --since is not specified, implies '--since 1m ago'.",
+    )
+    parser.add_argument(
+        "--lines",
+        "-n",
+        default=None,
+        type=str,
+        help=(
+            "Only show latest N log lines. "
+            "If '+' prefix is used, show oldest N log lines. "
+            "Ignored if --follow is used."
+        ),
+    )
+    parser.set_defaults(func=_logs)
+
+
 def add_parser(main_subparsers, parents):
     runners_help = "Manage fal runners."
     parser = main_subparsers.add_parser(
@@ -217,3 +567,4 @@ def add_parser(main_subparsers, parents):
 
     _add_kill_parser(subparsers, parents)
     _add_list_parser(subparsers, parents)
+    _add_logs_parser(subparsers, parents)

fal/sdk.py

@@ -38,6 +38,7 @@ FAL_SERVERLESS_DEFAULT_KEEP_ALIVE = 10
 FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING = 1
 FAL_SERVERLESS_DEFAULT_MIN_CONCURRENCY = 0
 FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER = 0
+FAL_SERVERLESS_DEFAULT_CONCURRENCY_BUFFER_PERC = 0
 ALIAS_AUTH_MODES = ["public", "private", "shared"]
 
 logger = get_logger(__name__)
@@ -45,7 +46,8 @@ logger = get_logger(__name__)
 patch_pickle()
 
 
-AuthMode = Optional[Literal["public", "private", "shared"]]
+AuthModeLiteral = Literal["public", "private", "shared"]
+DeploymentStrategyLiteral = Literal["recreate", "rolling"]
 
 
 class ServerCredentials:
@@ -237,6 +239,7 @@ class ApplicationInfo:
     active_runners: int
     min_concurrency: int
     concurrency_buffer: int
+    concurrency_buffer_perc: int
     machine_types: list[str]
     request_timeout: int
     startup_timeout: int
@@ -255,6 +258,7 @@ class AliasInfo:
     active_runners: int
     min_concurrency: int
     concurrency_buffer: int
+    concurrency_buffer_perc: int
     machine_types: list[str]
     request_timeout: int
     startup_timeout: int
@@ -403,6 +407,7 @@ def _from_grpc_application_info(
         active_runners=message.active_runners,
         min_concurrency=message.min_concurrency,
         concurrency_buffer=message.concurrency_buffer,
+        concurrency_buffer_perc=message.concurrency_buffer_perc,
         machine_types=list(message.machine_types),
         request_timeout=message.request_timeout,
         startup_timeout=message.startup_timeout,
@@ -432,6 +437,7 @@ def _from_grpc_alias_info(message: isolate_proto.AliasInfo) -> AliasInfo:
         active_runners=message.active_runners,
         min_concurrency=message.min_concurrency,
         concurrency_buffer=message.concurrency_buffer,
+        concurrency_buffer_perc=message.concurrency_buffer_perc,
         machine_types=list(message.machine_types),
         request_timeout=message.request_timeout,
         startup_timeout=message.startup_timeout,
@@ -524,6 +530,7 @@ class MachineRequirements:
     max_multiplexing: int | None = None
     min_concurrency: int | None = None
     concurrency_buffer: int | None = None
+    concurrency_buffer_perc: int | None = None
     request_timeout: int | None = None
     startup_timeout: int | None = None
 
@@ -617,12 +624,12 @@ class FalServerlessConnection:
         function: Callable[..., ResultT],
         environments: list[isolate_proto.EnvironmentDefinition],
         application_name: str | None = None,
-        auth_mode: AuthMode = None,
+        auth_mode: Optional[AuthModeLiteral] = None,
         *,
         serialization_method: str = _DEFAULT_SERIALIZATION_METHOD,
         machine_requirements: MachineRequirements | None = None,
         metadata: dict[str, Any] | None = None,
-        deployment_strategy: Literal["recreate", "rolling"] = "recreate",
+        deployment_strategy: DeploymentStrategyLiteral,
         scale: bool = True,
         private_logs: bool = False,
     ) -> Iterator[isolate_proto.RegisterApplicationResult]:
@@ -643,6 +650,7 @@ class FalServerlessConnection:
                 max_concurrency=machine_requirements.max_concurrency,
                 min_concurrency=machine_requirements.min_concurrency,
                 concurrency_buffer=machine_requirements.concurrency_buffer,
+                concurrency_buffer_perc=machine_requirements.concurrency_buffer_perc,
                 max_multiplexing=machine_requirements.max_multiplexing,
                 request_timeout=machine_requirements.request_timeout,
                 startup_timeout=machine_requirements.startup_timeout,
@@ -693,6 +701,7 @@ class FalServerlessConnection:
         max_concurrency: int | None = None,
         min_concurrency: int | None = None,
         concurrency_buffer: int | None = None,
+        concurrency_buffer_perc: int | None = None,
         request_timeout: int | None = None,
         startup_timeout: int | None = None,
         valid_regions: list[str] | None = None,
@@ -705,6 +714,7 @@ class FalServerlessConnection:
             max_concurrency=max_concurrency,
             min_concurrency=min_concurrency,
             concurrency_buffer=concurrency_buffer,
+            concurrency_buffer_perc=concurrency_buffer_perc,
             request_timeout=request_timeout,
             startup_timeout=startup_timeout,
             valid_regions=valid_regions,
@@ -758,6 +768,7 @@ class FalServerlessConnection:
                 max_multiplexing=machine_requirements.max_multiplexing,
                 min_concurrency=machine_requirements.min_concurrency,
                 concurrency_buffer=machine_requirements.concurrency_buffer,
+                concurrency_buffer_perc=machine_requirements.concurrency_buffer_perc,
                 request_timeout=machine_requirements.request_timeout,
                 startup_timeout=machine_requirements.startup_timeout,
             )
@@ -783,7 +794,7 @@ class FalServerlessConnection:
         self,
         alias: str,
         revision: str,
-        auth_mode: AuthMode,
+        auth_mode: Optional[AuthModeLiteral],
     ) -> AliasInfo:
         if auth_mode == "public":
             auth = isolate_proto.ApplicationAuthMode.PUBLIC

{fal-1.41.1.dist-info → fal-1.43.0.dist-info}/METADATA

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: fal
-Version: 1.41.1
+Version: 1.43.0
 Summary: fal is an easy-to-use Serverless Python Framework
 Author: Features & Labels <support@fal.ai>
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: isolate[build]<0.21.0,>=0.18.0
-Requires-Dist: isolate-proto<0.18.0,>=0.17.0
+Requires-Dist: isolate-proto<0.19.0,>=0.18.0
 Requires-Dist: grpcio<2,>=1.64.0
 Requires-Dist: dill==0.3.7
 Requires-Dist: cloudpickle==3.0.0
@@ -25,6 +25,7 @@ Requires-Dist: pydantic!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,<2.11
 Requires-Dist: fastapi<1,>=0.99.1
 Requires-Dist: starlette-exporter>=0.21.0
 Requires-Dist: httpx>=0.15.4
+Requires-Dist: httpx-sse
 Requires-Dist: attrs>=21.3.0
 Requires-Dist: python-dateutil<3,>=2.8.0
 Requires-Dist: types-python-dateutil<3,>=2.8.0

{fal-1.41.1.dist-info → fal-1.43.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
 fal/__init__.py,sha256=wXs1G0gSc7ZK60-bHe-B2m0l_sA6TrFk4BxY0tMoLe8,784
 fal/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
-fal/_fal_version.py,sha256=x1oDUpBFFYjPR-booVer5a9xgxhmXjRQm7FkCWuLIW4,706
+fal/_fal_version.py,sha256=9ytRZ2Yka4_txqqqY2iXWd2yQiXsjbUMCnR5a5N5uWw,706
 fal/_serialization.py,sha256=npXNsFJ5G7jzBeBIyVMH01Ww34mGY4XWhHpRbSrTtnQ,7598
 fal/_version.py,sha256=1BbTFnucNC_6ldKJ_ZoC722_UkW4S9aDBSW9L0fkKAw,2315
-fal/api.py,sha256=U_TBUBhkIvA5wFVOeqQejk-8Yxhy4pgWY4DLoelWxjU,49369
-fal/app.py,sha256=V4aBmtRpn7ysiuoX2ojSu4FyJ-T6ee14koIJ1VSQ0Dw,25990
+fal/api.py,sha256=6LkGbbqGUC4tcMBlTL-l7DBkl7t9FpZFSZY1doIdI5o,50284
+fal/app.py,sha256=4CGoHBxHQkpjpSlfYi-CCjVQ2A6BDX3qaH2JYv_zaoc,26008
 fal/apps.py,sha256=pzCd2mrKl5J_4oVc40_pggvPtFahXBCdrZXWpnaEJVs,12130
 fal/config.py,sha256=1HRaOJFOAjB7fbQoEPCSH85gMvEEMIMPeupVWgrHVgU,3572
 fal/container.py,sha256=FTsa5hOW4ars-yV1lUoc0BNeIIvAZcpw7Ftyt3A4m_w,2000
@@ -13,7 +13,7 @@ fal/flags.py,sha256=QonyDM7R2GqfAB1bJr46oriu-fHJCkpUwXuSdanePWg,987
 fal/project.py,sha256=QgfYfMKmNobMPufrAP_ga1FKcIAlSbw18Iar1-0qepo,2650
 fal/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 fal/rest_client.py,sha256=kGBGmuyHfX1lR910EoKCYPjsyU8MdXawT_cW2q8Sajc,568
-fal/sdk.py,sha256=Ed5GoQ8F4NoovG5B4X32Z72-yXP8Ji2TZ1kPczOSgc4,28240
+fal/sdk.py,sha256=13NXGsuoiXM94zzZi9p7PwWSeucYH8Yez6obWa64LBc,28891
 fal/sync.py,sha256=ZuIJA2-hTPNANG9B_NNJZUsO68EIdTH0dc9MzeVE2VU,4340
 fal/utils.py,sha256=iQTBG3-i6JZgHkkwbY_I4210g0xoW-as51yrke608u0,2208
 fal/workflows.py,sha256=Zl4f6Bs085hY40zmqScxDUyCu7zXkukDbW02iYOLTTI,14805
@@ -21,23 +21,23 @@ fal/auth/__init__.py,sha256=mtyQou8DGHC-COjW9WbtRyyzjyt7fMlhVmsB4U-CBh4,6509
 fal/auth/auth0.py,sha256=g5OgEKe4rsbkLQp6l7EauOAVL6WsmKjuA1wmzmyvvhc,5354
 fal/auth/local.py,sha256=sndkM6vKpeVny6NHTacVlTbiIFqaksOmw0Viqs_RN1U,1790
 fal/cli/__init__.py,sha256=padK4o0BFqq61kxAA1qQ0jYr2SuhA2mf90B3AaRkmJA,37
-fal/cli/_utils.py,sha256=ulYezhr3G29nTIF8MDQ6tsW01Oj1zPo-YSqMoBi05Ic,1871
+fal/cli/_utils.py,sha256=XwYoJr8SahaKB9OkGkw178FBpSeFAB-GqDXUQgGoFRE,2196
 fal/cli/api.py,sha256=ZuDE_PIC-czzneTAWMwvC7P7WnwIyluNZSuJqzCFhqI,2640
-fal/cli/apps.py,sha256=8ChoOYf2GeRSDN0w5VgDnWqdAqROlyDyQunciL-C8z4,12545
+fal/cli/apps.py,sha256=YZGF9slwGYtkU6PjMypatcICu606lLnpIwldO2N4p1I,13045
 fal/cli/auth.py,sha256=ZLjxuF4LobETJ2CLGMj_QurE0PiJxzKdFJZkux8uLHM,5977
 fal/cli/cli_nested_json.py,sha256=veSZU8_bYV3Iu1PAoxt-4BMBraNIqgH5nughbs2UKvE,13539
 fal/cli/create.py,sha256=a8WDq-nJLFTeoIXqpb5cr7GR7YR9ZZrQCawNm34KXXE,627
 fal/cli/debug.py,sha256=mTCjSpEZaNKcX225VZtry-BspFKSHURUuxUFuX6x5Cc,1488
-fal/cli/deploy.py,sha256=aezafp-g8vvLoARl1i84uGd-zIR1TtlSKi9E0dm-Z7E,8703
+fal/cli/deploy.py,sha256=vX8TpLwoyoLZnK03B005MEBi3wP0M5Pm6AKQ2tHOyjM,8903
 fal/cli/doctor.py,sha256=8SZrYG9Ku0F6LLUHtFdKopdIgZfFkw5E3Mwrxa9KOSk,1613
 fal/cli/files.py,sha256=-j0q4g53A7CWSczGLdfeUCTSd4zXoV3pfZFdman7JOw,3450
 fal/cli/keys.py,sha256=iQVMr3WT8CUqSQT3qeCCiy6rRwoux9F-UEaC4bCwMWo,3754
 fal/cli/main.py,sha256=LDy3gze9TRsvGa4uSNc8NMFmWMLpsyoC-msteICNiso,3371
-fal/cli/parser.py,sha256=PZi5MWS4Z-3YSPe6np_F87ay4kF6gaYxlP0avByPr-0,5222
+fal/cli/parser.py,sha256=siSY1kxqczZIs3l_jLwug_BpVzY_ZqHpewON3am83Ow,6658
 fal/cli/profile.py,sha256=PAY_ffifCT71VJ8VxfDVaXPT0U1oN8drvWZDFRXwvek,6678
 fal/cli/queue.py,sha256=9Kid3zR6VOFfAdDgnqi2TNN4ocIv5Vs61ASEZnwMa9o,2713
 fal/cli/run.py,sha256=nAC12Qss4Fg1XmV0qOS9RdGNLYcdoHeRgQMvbTN4P9I,1202
-fal/cli/runners.py,sha256=AXUB2pq9Ot0VU2cOeJydSgmgTlUm4i6iNgJOClO7ZZw,6533
+fal/cli/runners.py,sha256=OWSsvk01IkwQhibewZQgC-iWMOXl43tWJSi9F81x8n4,17481
 fal/cli/secrets.py,sha256=HfIeO2IZpCEiBC6Cs5Kpi3zckfDnc7GsLwLdgj3NnPU,3085
 fal/cli/teams.py,sha256=_JcNcf659ZoLBFOxKnVP5A6Pyk1jY1vh4_xzMweYIDo,1285
 fal/console/__init__.py,sha256=lGPUuTqIM9IKTa1cyyA-MA2iZJKVHp2YydsITZVlb6g,148
@@ -143,8 +143,8 @@ openapi_fal_rest/models/workflow_node_type.py,sha256=-FzyeY2bxcNmizKbJI8joG7byRi
 openapi_fal_rest/models/workflow_schema.py,sha256=4K5gsv9u9pxx2ItkffoyHeNjBBYf6ur5bN4m_zePZNY,2019
 openapi_fal_rest/models/workflow_schema_input.py,sha256=2OkOXWHTNsCXHWS6EGDFzcJKkW5FIap-2gfO233EvZQ,1191
 openapi_fal_rest/models/workflow_schema_output.py,sha256=EblwSPAGfWfYVWw_WSSaBzQVju296is9o28rMBAd0mc,1196
-fal-1.41.1.dist-info/METADATA,sha256=T2VrmT4Q15Dkw1U9UNmZecjASDlYvAN9POQ29j4-KUk,4132
-fal-1.41.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-fal-1.41.1.dist-info/entry_points.txt,sha256=32zwTUC1U1E7nSTIGCoANQOQ3I7-qHG5wI6gsVz5pNU,37
-fal-1.41.1.dist-info/top_level.txt,sha256=r257X1L57oJL8_lM0tRrfGuXFwm66i1huwQygbpLmHw,21
-fal-1.41.1.dist-info/RECORD,,
+fal-1.43.0.dist-info/METADATA,sha256=zPgp2LNXDvJIgI1bRTlb9nkfzNwQFD9ev1jwK9lPT9Q,4157
+fal-1.43.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fal-1.43.0.dist-info/entry_points.txt,sha256=32zwTUC1U1E7nSTIGCoANQOQ3I7-qHG5wI6gsVz5pNU,37
+fal-1.43.0.dist-info/top_level.txt,sha256=r257X1L57oJL8_lM0tRrfGuXFwm66i1huwQygbpLmHw,21
+fal-1.43.0.dist-info/RECORD,,