feat(app): implement FAL_RUNNER_STATE env var

projects/fal/src/fal/app.py

@@ -485,6 +485,8 @@ def collect_routes(self) -> dict[RouteSignature, Callable[..., Any]]:
 
     @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
@@ -493,9 +495,13 @@ async def lifespan(self, app: fastapi.FastAPI):
             _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):

projects/fal/tests/unit/test_app.py

@@ -1,5 +1,9 @@
 from __future__ import annotations
 
+import os
+
+import pytest
+
 from fal import App
 from fal.container import ContainerImage
 
@@ -93,3 +97,32 @@ class LeakCheckApp(App):
     assert "machine_type" not in hk
     assert "num_gpus" not in hk
     assert "app_auth" not in hk
+
+
+@pytest.mark.asyncio
+async def test_runner_state_lifecycle_complete():
+    """Test that FAL_RUNNER_STATE transitions through all phases correctly"""
+    states = []
+
+    class StateCheckApp(App):
+        def setup(self):
+            states.append(("setup", os.getenv("FAL_RUNNER_STATE")))
+
+        def teardown(self):
+            states.append(("teardown", os.getenv("FAL_RUNNER_STATE")))
+
+    app = StateCheckApp(_allow_init=True)
+
+    # Create a mock FastAPI app
+    import fastapi
+
+    fastapi_app = fastapi.FastAPI()
+
+    async with app.lifespan(fastapi_app):
+        states.append(("running", os.getenv("FAL_RUNNER_STATE")))
+
+    # Verify the full lifecycle
+    assert len(states) == 3
+    assert states[0] == ("setup", "SETUP")
+    assert states[1] == ("running", "RUNNING")
+    assert states[2] == ("teardown", "STOPPING")