Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

refactor: extract NotebookWorkspace from AppFileRouter (#9448)

Myles Scolnickd559ab7933c6
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.py
index 1850b5ff89..4703d2c077 100644
--- a/marimo/_cli/cli.py
+++ b/marimo/_cli/cli.py
@@ -45,14 +45,18 @@ from marimo._cli.utils import (
from marimo._config.settings import GLOBAL_SETTINGS
from marimo._lint import run_check
from marimo._mcp.setup import McpType
-from marimo._server.file_router import (
- AppFileRouter,
- LazyListOfFilesAppFileRouter,
- flatten_files,
-)
from marimo._server.files.directory_scanner import DirectoryScanner
from marimo._server.models.home import MarimoFile
from marimo._server.start import start
+from marimo._server.workspace import (
+ DirectoryWorkspace,
+ EmptyWorkspace,
+ FixedFilesWorkspace,
+ NotebookWorkspace,
+ SingleFileWorkspace,
+ flatten_files,
+ infer_workspace,
+)
from marimo._session.model import SessionMode
from marimo._tutorials import (
Tutorial,
@@ -580,7 +584,7 @@ def edit(
check_for_updates(print_latest_version)
start(
- file_router=AppFileRouter.infer(name),
+ workspace=infer_workspace(name),
development_mode=GLOBAL_SETTINGS.DEVELOPMENT_MODE,
quiet=GLOBAL_SETTINGS.QUIET,
host=host,
@@ -735,7 +739,7 @@ def new(
run_in_sandbox(sys.argv[1:], name=None, additional_features=["lsp"])
return
- file_router: AppFileRouter | None = None
+ workspace: NotebookWorkspace | None = None
if prompt is None:
# We support unix-style prompting, cat prompt.txt | marimo new
@@ -763,7 +767,7 @@ def new(
suffix=".py", mode="w", encoding="utf-8", delete=False
) as temp_file:
temp_file.write(notebook_content)
- file_router = AppFileRouter.infer(temp_file.name)
+ workspace = infer_workspace(temp_file.name)
def _cleanup() -> None:
try:
@@ -783,11 +787,11 @@ def new(
f"Failed to generate notebook: {e!s}"
) from e
- if file_router is None:
- file_router = AppFileRouter.new_file()
+ if workspace is None:
+ workspace = EmptyWorkspace()
start(
- file_router=file_router,
+ workspace=workspace,
development_mode=GLOBAL_SETTINGS.DEVELOPMENT_MODE,
quiet=GLOBAL_SETTINGS.QUIET,
host=host,
@@ -900,12 +904,12 @@ def _collect_marimo_files(paths: list[str]) -> _CollectedRunFiles:
return _CollectedRunFiles(files=files, root_dir=root_dir)
-def _create_run_file_router(
+def _create_run_workspace(
validated_paths: list[str], *, watch: bool
-) -> AppFileRouter:
- """Create the file router for `marimo run`.
+) -> NotebookWorkspace:
+ """Create the workspace for `marimo run`.
- For `--watch` with a single directory, use a lazy directory router so the
+ For `--watch` with a single directory, use a directory workspace so the
gallery index can reflect file additions/deletions on subsequent requests.
For all other invocation shapes, preserve static snapshot behavior.
"""
@@ -914,22 +918,18 @@ def _create_run_file_router(
and len(validated_paths) == 1
and Path(validated_paths[0]).is_dir()
):
- return LazyListOfFilesAppFileRouter(
- validated_paths[0], include_markdown=True
- )
+ return DirectoryWorkspace(validated_paths[0], include_markdown=True)
has_directory = any(Path(path).is_dir() for path in validated_paths)
is_multi = has_directory or len(validated_paths) > 1
if is_multi:
marimo_files = _collect_marimo_files(validated_paths)
- return AppFileRouter.from_files(
+ return FixedFilesWorkspace(
marimo_files.files,
directory=marimo_files.root_dir,
- allow_single_file_key=False,
- allow_dynamic=False,
)
- return AppFileRouter.from_filename(MarimoPath(validated_paths[0]))
+ return SingleFileWorkspace.from_path(MarimoPath(validated_paths[0]))
@main.command(
@@ -1210,10 +1210,10 @@ def run(
"pyzmq",
)
- file_router = _create_run_file_router(validated_paths, watch=watch)
+ workspace = _create_run_workspace(validated_paths, watch=watch)
start(
- file_router=file_router,
+ workspace=workspace,
development_mode=GLOBAL_SETTINGS.DEVELOPMENT_MODE,
quiet=GLOBAL_SETTINGS.QUIET,
host=host,
@@ -1342,7 +1342,7 @@ def tutorial(
path = create_temp_tutorial_file(name, temp_dir)
start(
- file_router=AppFileRouter.from_filename(path),
+ workspace=SingleFileWorkspace.from_path(path),
development_mode=GLOBAL_SETTINGS.DEVELOPMENT_MODE,
quiet=GLOBAL_SETTINGS.QUIET,
host=host,
diff --git a/marimo/_cli/export/_common.py b/marimo/_cli/export/_common.py
index 0f6d0b2554..30c578ab27 100644
--- a/marimo/_cli/export/_common.py
+++ b/marimo/_cli/export/_common.py
@@ -8,8 +8,8 @@ from typing import TYPE_CHECKING, Any
import click
-from marimo._server.file_router import flatten_files
from marimo._server.files.directory_scanner import DirectoryScanner
+from marimo._server.workspace import flatten_files
from marimo._utils.http import HTTPException, HTTPStatus
from marimo._utils.marimo_path import MarimoPath
diff --git a/marimo/_server/api/endpoints/assets.py b/marimo/_server/api/endpoints/assets.py
index 7fc203e6fc..793da1ca3f 100644
--- a/marimo/_server/api/endpoints/assets.py
+++ b/marimo/_server/api/endpoints/assets.py
@@ -194,16 +194,14 @@ def og_thumbnail(*, request: Request) -> Response:
app_state = AppState(request)
file_key = (
app_state.query_params(FILE_QUERY_PARAM_KEY)
- or app_state.session_manager.file_router.get_unique_file_key()
+ or app_state.session_manager.workspace.get_unique_file_key()
)
if not file_key:
raise HTTPException(
status_code=HTTPStatus.NOT_FOUND, detail="File not found"
)
- notebook_path = app_state.session_manager.file_router.resolve_file_path(
- file_key
- )
+ notebook_path = app_state.session_manager.workspace.resolve(file_key)
if notebook_path is None:
raise HTTPException(
status_code=HTTPStatus.NOT_FOUND, detail="File not found"
@@ -313,7 +311,7 @@ async def index(request: Request) -> Response:
file_key_from_query = app_state.query_params(FILE_QUERY_PARAM_KEY)
file_key = (
file_key_from_query
- or app_state.session_manager.file_router.get_unique_file_key()
+ or app_state.session_manager.workspace.get_unique_file_key()
)
# Try local index.html first, fallback to asset_url if local file doesn't exist
@@ -374,7 +372,7 @@ async def index(request: Request) -> Response:
LOGGER.debug("Failed to pre-compute notebook snapshot")
filename = app_manager.filename
- directory = app_state.session_manager.file_router.directory
+ directory = app_state.session_manager.workspace.directory
lsp_workspace = _resolve_lsp_workspace(filename, directory)
# Make filename relative to file router's directory if possible
diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.py
index 638585f86e..1b94f81fa3 100644
--- a/marimo/_server/api/endpoints/execution.py
+++ b/marimo/_server/api/endpoints/execution.py
@@ -18,7 +18,6 @@ from marimo._server.api.endpoints.ws.ws_connection_validator import (
)
from marimo._server.api.endpoints.ws_endpoint import DOC_MANAGER
from marimo._server.api.utils import dispatch_control_request, parse_request
-from marimo._server.file_router import MarimoFileKey
from marimo._server.models.models import (
BaseResponse,
DebugCellRequest,
@@ -32,6 +31,7 @@ from marimo._server.models.models import (
)
from marimo._server.router import APIRouter
from marimo._server.uvicorn_utils import close_uvicorn
+from marimo._server.workspace import MarimoFileKey
from marimo._types.ids import ConsumerId
if TYPE_CHECKING:
@@ -426,7 +426,7 @@ async def restart_session(
# Close RTC doc if it exists
file_key: MarimoFileKey | None = (
app_state.query_params(FILE_QUERY_PARAM_KEY)
- or session_manager.file_router.get_unique_file_key()
+ or session_manager.workspace.get_unique_file_key()
or session.app_file_manager.path
)
if file_key is not None:
@@ -461,7 +461,7 @@ async def shutdown(
LOGGER.debug("Received shutdown request")
app_state = AppState(request)
session_manager = app_state.session_manager
- file_router = session_manager.file_router
+ workspace = session_manager.workspace
def shutdown_server() -> None:
app_state.session_manager.shutdown()
@@ -470,7 +470,7 @@ async def shutdown(
# If we are only operating on a single file (new or explicit file),
# and there are no other sessions (user may have opened another notebook
# from the file explorer) then we should shutdown the whole server
- key = file_router.get_unique_file_key()
+ key = workspace.get_unique_file_key()
if key and len(session_manager.sessions) <= 1:
shutdown_server()
return SuccessResponse()
@@ -516,7 +516,7 @@ async def takeover_endpoint(
file_key: MarimoFileKey | None = (
app_state.query_params(FILE_QUERY_PARAM_KEY)
- or app_state.session_manager.file_router.get_unique_file_key()
+ or app_state.session_manager.workspace.get_unique_file_key()
)
if file_key is None:
LOGGER.error("No file key provided")
diff --git a/marimo/_server/api/endpoints/file_explorer.py b/marimo/_server/api/endpoints/file_explorer.py
index 6a9451672c..f31ec6c55b 100644
--- a/marimo/_server/api/endpoints/file_explorer.py
+++ b/marimo/_server/api/endpoints/file_explorer.py
@@ -69,8 +69,8 @@ async def list_files(
"""
app_state = AppState(request)
body = await parse_request(request, cls=FileListRequest)
- # Use file router's directory as default, fall back to cwd
- directory = app_state.session_manager.file_router.directory
+ # Use workspace's directory as default, fall back to cwd
+ directory = app_state.session_manager.workspace.directory
root = body.path or directory or file_system.get_root()
files = file_system.list_files(root)
return FileListResponse(files=files, root=root)
diff --git a/marimo/_server/api/endpoints/files.py b/marimo/_server/api/endpoints/files.py
index 24ff145f29..45550b1596 100644
--- a/marimo/_server/api/endpoints/files.py
+++ b/marimo/_server/api/endpoints/files.py
@@ -111,9 +111,9 @@ async def rename_file(
"""
body = await parse_request(request, cls=RenameNotebookRequest)
app_state = AppState(request)
- directory = app_state.session_manager.file_router.directory
+ directory = app_state.session_manager.workspace.directory
- # Resolve relative filenames against the file router's directory
+ # Resolve relative filenames against the workspace's directory
if not Path(body.filename).is_absolute() and directory:
body.filename = str(Path(directory) / body.filename)
@@ -165,9 +165,9 @@ async def save(
"""
app_state = AppState(request)
body = await parse_request(request, cls=SaveNotebookRequest)
- directory = app_state.session_manager.file_router.directory
+ directory = app_state.session_manager.workspace.directory
- # Resolve relative filenames against the file router's directory
+ # Resolve relative filenames against the workspace's directory
if body.filename and not Path(body.filename).is_absolute():
if directory:
body.filename = str(Path(directory) / body.filename)
@@ -213,8 +213,8 @@ async def copy(
app_state = AppState(request)
body = await parse_request(request, cls=CopyNotebookRequest)
- # Resolve relative filenames against the file router's directory
- directory = app_state.session_manager.file_router.directory
+ # Resolve relative filenames against the workspace's directory
+ directory = app_state.session_manager.workspace.directory
if directory:
if body.source and not Path(body.source).is_absolute():
body.source = str(Path(directory) / body.source)
diff --git a/marimo/_server/api/endpoints/home.py b/marimo/_server/api/endpoints/home.py
index 48caf3321e..a16b660313 100644
--- a/marimo/_server/api/endpoints/home.py
+++ b/marimo/_server/api/endpoints/home.py
@@ -13,10 +13,6 @@ from starlette.responses import JSONResponse
from marimo import _loggers
from marimo._server.api.deps import AppState
from marimo._server.api.utils import parse_request
-from marimo._server.file_router import (
- count_files,
- flatten_files,
-)
from marimo._server.files.directory_scanner import DirectoryScanner
from marimo._server.models.home import (
MarimoFile,
@@ -28,6 +24,10 @@ from marimo._server.models.home import (
WorkspaceFilesResponse,
)
from marimo._server.router import APIRouter
+from marimo._server.workspace import (
+ count_files,
+ flatten_files,
+)
from marimo._session.model import ConnectionState, SessionMode
from marimo._tutorials import create_temp_tutorial_file # type: ignore
from marimo._utils.http import HTTPException, HTTPStatus
@@ -60,9 +60,9 @@ async def read_code(
$ref: "#/components/schemas/RecentFilesResponse"
"""
app_state = AppState(request)
- # Pass the file router's directory to filter and relativize paths
+ # Pass the workspace's directory to filter and relativize paths
directory = None
- dir_str = app_state.session_manager.file_router.directory
+ dir_str = app_state.session_manager.workspace.directory
if dir_str:
directory = pathlib.Path(dir_str)
files = app_state.session_manager.recents.get_recents(directory)
@@ -102,23 +102,21 @@ async def workspace_files(
if session_manager.watch:
# In watched folder mode, refresh the index to include new/removed files since the previous request.
- session_manager.file_router.mark_stale()
+ session_manager.workspace.invalidate()
base_url = app_state.base_url
mode = session_manager.mode.value
def get_files_with_metadata() -> list[FileInfo]:
- files = session_manager.file_router.files
+ files = session_manager.workspace.files
marimo_files = [
file for file in flatten_files(files) if file.is_marimo_file
]
result: list[FileInfo] = []
for file in marimo_files:
try:
- resolved_path = (
- session_manager.file_router.resolve_file_path(
- file.path
- )
+ resolved_path = session_manager.workspace.resolve(
+ file.path
)
except HTTPException as e:
if e.status_code == HTTPStatus.NOT_FOUND:
@@ -155,21 +153,19 @@ async def workspace_files(
has_more = file_count >= MAX_FILES
return WorkspaceFilesResponse(
files=marimo_files,
- root=session_manager.file_router.directory or "",
+ root=session_manager.workspace.directory or "",
has_more=has_more,
file_count=file_count,
)
- # Mark stale (no-op for routers without cached listings) and toggle
- # markdown inclusion (no-op-returns-self for non-directory routers).
- session_manager.file_router.mark_stale()
- session_manager.file_router = session_manager.file_router.toggle_markdown(
- body.include_markdown
- )
- root = session_manager.file_router.directory or ""
+ # Both calls are no-ops on workspaces that don't support these
+ # capabilities (single-file, fixed-files, empty).
+ session_manager.workspace.invalidate()
+ session_manager.workspace.set_include_markdown(body.include_markdown)
+ root = session_manager.workspace.directory or ""
# Run file scanning in thread pool to avoid blocking the server
- files = await asyncio.to_thread(lambda: session_manager.file_router.files)
+ files = await asyncio.to_thread(lambda: session_manager.workspace.files)
file_count = count_files(files)
has_more = file_count >= MAX_FILES
@@ -184,8 +180,8 @@ async def workspace_files(
def _get_active_sessions(app_state: AppState) -> list[MarimoFile]:
"""Get list of active sessions with prettified paths."""
- # Get directory from file router for path relativization
- base_dir = app_state.session_manager.file_router.directory
+ # Get directory from workspace for path relativization
+ base_dir = app_state.session_manager.workspace.directory
files: list[MarimoFile] = []
for session_id, session in app_state.session_manager.sessions.items():
@@ -287,11 +283,11 @@ async def tutorial(
atexit.register(temp_dir.cleanup)
- # Register the temp file/directory with the router so it can be accessed.
- # Each method is a no-op on routers that don't support that capability.
+ # Register the temp file/directory with the workspace so it can be accessed.
+ # Each method is a no-op on workspaces that don't support that capability.
app_state = AppState(request)
- app_state.session_manager.file_router.register_temp_dir(temp_dir.name)
- app_state.session_manager.file_router.register_allowed_file(
+ app_state.session_manager.workspace.register_temp_dir(temp_dir.name)
+ app_state.session_manager.workspace.register_allowed_path(
path.absolute_name
)
diff --git a/marimo/_server/api/endpoints/ws/ws_connection_validator.py b/marimo/_server/api/endpoints/ws/ws_connection_validator.py
index 4d8ae26e91..21f65a3d03 100644
--- a/marimo/_server/api/endpoints/ws/ws_connection_validator.py
+++ b/marimo/_server/api/endpoints/ws/ws_connection_validator.py
@@ -11,7 +11,7 @@ from marimo import _loggers
from marimo._server.api.auth import validate_auth
from marimo._server.api.deps import AppState
from marimo._server.codes import WebSocketCodes
-from marimo._server.file_router import MarimoFileKey
+from marimo._server.workspace import MarimoFileKey
from marimo._types.ids import SessionId
LOGGER = _loggers.marimo_logger()
@@ -73,7 +73,7 @@ class WebSocketConnectionValidator:
# Extract file_key
file_key: MarimoFileKey | None = (
self.app_state.query_params(FILE_QUERY_PARAM_KEY)
- or self.app_state.session_manager.file_router.get_unique_file_key()
+ or self.app_state.session_manager.workspace.get_unique_file_key()
)
if file_key is None:
@@ -106,7 +106,7 @@ class WebSocketConnectionValidator:
"""
file_key: MarimoFileKey | None = (
self.app_state.query_params(FILE_QUERY_PARAM_KEY)
- or self.app_state.session_manager.file_router.get_unique_file_key()
+ or self.app_state.session_manager.workspace.get_unique_file_key()
)
if file_key is None:
diff --git a/marimo/_server/api/endpoints/ws/ws_kernel_ready.py b/marimo/_server/api/endpoints/ws/ws_kernel_ready.py
index c2b049f449..f3bdea78cf 100644
--- a/marimo/_server/api/endpoints/ws/ws_kernel_ready.py
+++ b/marimo/_server/api/endpoints/ws/ws_kernel_ready.py
@@ -18,9 +18,9 @@ from marimo._session.model import SessionMode
from marimo._types.ids import CellId_t
if TYPE_CHECKING:
- from marimo._server.file_router import MarimoFileKey
from marimo._server.rtc.doc import LoroDocManager
from marimo._server.session_manager import SessionManager
+ from marimo._server.workspace import MarimoFileKey
from marimo._session import Session
LOGGER = _loggers.marimo_logger()
diff --git a/marimo/_server/api/endpoints/ws/ws_rtc_handler.py b/marimo/_server/api/endpoints/ws/ws_rtc_handler.py
index 2b0358ff42..6e0263ba56 100644
--- a/marimo/_server/api/endpoints/ws/ws_rtc_handler.py
+++ b/marimo/_server/api/endpoints/ws/ws_rtc_handler.py
@@ -12,8 +12,8 @@ if TYPE_CHECKING:
from loro import DiffEvent, ExportMode, LoroDoc
from starlette.websockets import WebSocket
- from marimo._server.file_router import MarimoFileKey
from marimo._server.rtc.doc import LoroDocManager
+ from marimo._server.workspace import MarimoFileKey
LOGGER = _loggers.marimo_logger()
diff --git a/marimo/_server/api/lifespans.py b/marimo/_server/api/lifespans.py
index 16b30a66dc..10903d0b08 100644
--- a/marimo/_server/api/lifespans.py
+++ b/marimo/_server/api/lifespans.py
@@ -13,7 +13,6 @@ from marimo._server.ai.tools.tool_manager import setup_tool_manager
from marimo._server.api.deps import AppState, AppStateBase
from marimo._server.api.interrupt import InterruptHandler
from marimo._server.api.utils import open_url_in_browser
-from marimo._server.file_router import AppFileRouter
from marimo._server.lsp import any_lsp_server_running
from marimo._server.print import (
print_experimental_features,
@@ -26,6 +25,7 @@ from marimo._server.session_manager import SessionManager
from marimo._server.tokens import AuthToken
from marimo._server.utils import initialize_mimetypes
from marimo._server.uvicorn_utils import close_uvicorn
+from marimo._server.workspace import NEW_FILE
from marimo._session.model import SessionMode
from marimo._utils.subprocess import cancel_pending_reaps
@@ -159,18 +159,18 @@ async def logging(app: Starlette) -> AsyncIterator[None]:
state = AppState.from_app(app)
manager: SessionManager = state.session_manager
quiet = state.quiet
- file_router = manager.file_router
+ workspace = manager.workspace
mcp_server_enabled = state.mcp_server_enabled
skew_protection_enabled = state.skew_protection
# Startup message
if not quiet:
- file = file_router.maybe_get_single_file()
+ file = workspace.single_file()
print_startup(
file_name=file.name if file else None,
url=_startup_url(state),
run=manager.mode == SessionMode.RUN,
- new=file_router.get_unique_file_key() == AppFileRouter.NEW_FILE,
+ new=workspace.get_unique_file_key() == NEW_FILE,
network=state.host == "0.0.0.0",
startup_tip=state.startup_tip,
)
diff --git a/marimo/_server/asgi.py b/marimo/_server/asgi.py
index 7565891255..1eac5d9188 100644
--- a/marimo/_server/asgi.py
+++ b/marimo/_server/asgi.py
@@ -463,13 +463,13 @@ def create_asgi_app(
from marimo._config.config import PartialMarimoConfig
from marimo._config.manager import get_default_config_manager
from marimo._server.api import lifespans
- from marimo._server.file_router import AppFileRouter
from marimo._server.lsp import NoopLspServer
from marimo._server.main import create_starlette_app
from marimo._server.registry import LIFESPAN_REGISTRY
from marimo._server.session_manager import SessionManager
from marimo._server.tokens import AuthToken
from marimo._server.utils import initialize_asyncio
+ from marimo._server.workspace import SingleFileWorkspace
from marimo._session.model import SessionMode
from marimo._utils.lifespans import Lifespans
from marimo._utils.marimo_path import MarimoPath
@@ -544,7 +544,7 @@ def create_asgi_app(
)
session_manager = SessionManager(
- file_router=AppFileRouter.from_filename(MarimoPath(file_path)),
+ workspace=SingleFileWorkspace.from_path(MarimoPath(file_path)),
mode=SessionMode.RUN,
quiet=quiet,
include_code=include_code,
diff --git a/marimo/_server/file_router.py b/marimo/_server/file_router.py
deleted file mode 100644
index f7ef402da9..0000000000
--- a/marimo/_server/file_router.py
+++ /dev/null
@@ -1,450 +0,0 @@
-# Copyright 2026 Marimo. All rights reserved.
-from __future__ import annotations
-
-import abc
-import os
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from marimo import _loggers
-from marimo._server.app_defaults import AppDefaults
-from marimo._server.files.directory_scanner import DirectoryScanner
-from marimo._server.files.path_validator import PathValidator
-from marimo._server.models.files import FileInfo
-from marimo._server.models.home import MarimoFile
-from marimo._session.notebook import AppFileManager
-from marimo._utils.http import HTTPException, HTTPStatus
-from marimo._utils.marimo_path import MarimoPath
-from marimo._utils.paths import normalize_path
-
-if TYPE_CHECKING:
- from collections.abc import Iterator
-
-LOGGER = _loggers.marimo_logger()
-
-# Some unique identifier for a file
-MarimoFileKey = str
-
-
-class AppFileRouter(abc.ABC):
- """Abstract class for routing files to an AppFileManager."""
-
- NEW_FILE: MarimoFileKey = "__new__"
-
- @property
- def directory(self) -> str | None:
- return None
-
- @staticmethod
- def infer(path: str) -> AppFileRouter:
- if os.path.isfile(path):
- LOGGER.debug("Routing to file %s", path)
- return AppFileRouter.from_filename(MarimoPath(path))
- if os.path.isdir(path):
- LOGGER.debug("Routing to directory %s", path)
- return AppFileRouter.from_directory(path)
- raise HTTPException(
- status_code=HTTPStatus.BAD_REQUEST,
- detail=f"Path {path} is not a valid file or directory",
- )
-
- @staticmethod
- def from_filename(file: MarimoPath) -> AppFileRouter:
- files = [
- MarimoFile(
- name=file.relative_name,
- path=file.absolute_name,
- last_modified=file.last_modified,
- )
- ]
- return ListOfFilesAppFileRouter(files, allow_dynamic=True)
-
- @staticmethod
- def from_directory(directory: str) -> AppFileRouter:
- return LazyListOfFilesAppFileRouter(directory, include_markdown=False)
-
- @staticmethod
- def from_files(
- files: list[MarimoFile],
- *,
- directory: str | None = None,
- allow_single_file_key: bool = True,
- allow_dynamic: bool = False,
- ) -> AppFileRouter:
- return ListOfFilesAppFileRouter(
- files,
- directory=directory,
- allow_single_file_key=allow_single_file_key,
- allow_dynamic=allow_dynamic,
- )
-
- @staticmethod
- def new_file() -> AppFileRouter:
- return NewFileAppFileRouter()
-
- def get_single_app_file_manager(
- self,
- defaults: AppDefaults | None = None,
- ) -> AppFileManager:
- key = self.get_unique_file_key()
- assert key is not None, "Expected a single file"
- return self.get_file_manager(key, defaults)
-
- @abc.abstractmethod
- def get_file_manager(
- self,
- key: MarimoFileKey,
- defaults: AppDefaults | None = None,
- ) -> AppFileManager:
- """Given a key, return an ``AppFileManager``."""
-
- @abc.abstractmethod
- def resolve_file_path(self, key: MarimoFileKey) -> str | None:
- """Resolve a file key to an absolute file path, without loading the app.
-
- This is useful for endpoints that need file-backed resources (e.g.
- thumbnails) without the overhead of parsing/loading a notebook.
-
- Returns the absolute file path if resolvable, otherwise ``None`` (for
- the new-file sentinel).
- """
-
- @abc.abstractmethod
- def get_unique_file_key(self) -> MarimoFileKey | None:
- """
- If there is a unique file key, return it. Otherwise, return None.
- """
-
- @abc.abstractmethod
- def maybe_get_single_file(self) -> MarimoFile | None:
- """
- If there is a single file, return it. Otherwise, return None.
- """
-
- @property
- @abc.abstractmethod
- def files(self) -> list[FileInfo]:
- """
- Get all files in a recursive tree.
- """
-
- # Optional capabilities — subclasses override only if they support them.
-
- def register_allowed_file(self, filepath: str) -> None:
- """Allow a file path that wasn't part of the original collection.
-
- No-op by default; routers that maintain a fixed allowlist override.
- """
- del filepath
-
- def register_temp_dir(self, temp_dir: str) -> None:
- """Register a temp directory as allowed for file access.
-
- No-op by default; only directory-backed routers override.
- """
- del temp_dir
-
- def is_file_in_allowed_temp_dir(self, filepath: str) -> bool:
- """Whether a file lives inside an allowed temp directory.
-
- Returns ``False`` by default; only directory-backed routers override.
- """
- del filepath
- return False
-
- def mark_stale(self) -> None: # noqa: B027 — intentional no-op default
- """Invalidate any cached listing.
-
- No-op by default; lazy directory routers override.
- """
-
- def toggle_markdown(self, include_markdown: bool) -> AppFileRouter:
- """Return a router with markdown inclusion toggled.
-
- No-op by default — returns ``self``. Lazy directory routers override.
- """
- del include_markdown
- return self
-
-
-class NewFileAppFileRouter(AppFileRouter):
- def get_unique_file_key(self) -> MarimoFileKey | None:
- return AppFileRouter.NEW_FILE
-
- def maybe_get_single_file(self) -> MarimoFile | None:
- return None
-
- @property
- def files(self) -> list[FileInfo]:
- return []
-
- def get_file_manager(
- self,
- key: MarimoFileKey,
- defaults: AppDefaults | None = None,
- ) -> AppFileManager:
- defaults = defaults or AppDefaults()
- if key.startswith(AppFileRouter.NEW_FILE):
- return AppFileManager(None, defaults=defaults)
- # Fall back to loading any existing path. This is used by callers
- # (and tests) that bootstrap with ``new_file()`` but then create
- # sessions for concrete files.
- if os.path.exists(key):
- return AppFileManager(key, defaults=defaults)
- raise HTTPException(
- status_code=HTTPStatus.NOT_FOUND,
- detail=f"File {key} not found",
- )
-
- def resolve_file_path(self, key: MarimoFileKey) -> str | None:
- if key.startswith(AppFileRouter.NEW_FILE):
- return None
- if os.path.exists(key):
- return key
- raise HTTPException(
- status_code=HTTPStatus.NOT_FOUND,
- detail=f"File {key} not found",
- )
-
-
-class ListOfFilesAppFileRouter(AppFileRouter):
- def __init__(
- self,
- files: list[MarimoFile],
- directory: str | None = None,
- allow_single_file_key: bool = True,
- allow_dynamic: bool = False,
- ) -> None:
- self._files = files
- self._directory = directory
- self._allow_single_file_key = allow_single_file_key
- self._allow_dynamic = allow_dynamic
- self._allowed_paths = {
- str(normalize_path(Path(MarimoPath(file.path).absolute_name)))
- for file in files
- }
-
- @property
- def directory(self) -> str | None:
- return self._directory
-
- @property
- def files(self) -> list[FileInfo]:
- return [
- FileInfo(
- id=file.path,
- name=file.name,
- path=file.path,
- last_modified=file.last_modified,
- is_directory=False,
- is_marimo_file=True,
- )
- for file in self._files
- ]
-
- def get_file_manager(
- self,
- key: MarimoFileKey,
- defaults: AppDefaults | None = None,
- ) -> AppFileManager:
- defaults = defaults or AppDefaults()
-
- resolved_path = self.resolve_file_path(key)
- if resolved_path is None:
- return AppFileManager(None, defaults=defaults)
- return AppFileManager(resolved_path, defaults=defaults)
-
- def resolve_file_path(self, key: MarimoFileKey) -> str | None:
- if key.startswith(AppFileRouter.NEW_FILE):
- if self._allow_single_file_key:
- return None
- raise HTTPException(
- status_code=HTTPStatus.NOT_FOUND,
- detail=f"File {key} not found",
- )
-
- filepath = Path(key)
- if not filepath.is_absolute() and self._directory:
- filepath = Path(self._directory) / filepath
- normalized_path = normalize_path(filepath)
- absolute_path = str(normalized_path)
- if absolute_path not in self._allowed_paths:
- raise HTTPException(
- status_code=HTTPStatus.NOT_FOUND,
- detail=f"File {key} not found",
- )
-
- if normalized_path.exists():
- return absolute_path
-
- raise HTTPException(
- status_code=HTTPStatus.NOT_FOUND,
- detail=f"File {key} not found",
- )
-
- def get_unique_file_key(self) -> MarimoFileKey | None:
- if self._allow_single_file_key and len(self._files) == 1:
- return self._files[0].path
- return None
-
- def maybe_get_single_file(self) -> MarimoFile | None:
- if self._allow_single_file_key and len(self._files) == 1:
- return self._files[0]
- return None
-
- def register_allowed_file(self, filepath: str) -> None:
- """Allow a file path in this router.
-
- This extends the allowlist for files that were not part of the original
- collection and may live outside the router's base directory (for
- example, files created at runtime in a separate location).
- """
- if not self._allow_dynamic:
- return
- self._allowed_paths.add(
- str(normalize_path(Path(MarimoPath(filepath).absolute_name)))
- )
-
-
-class LazyListOfFilesAppFileRouter(AppFileRouter):
- def __init__(self, directory: str, include_markdown: bool) -> None:
- # Make directory absolute but don't resolve symlinks to preserve user paths
- abs_directory = Path(directory).absolute()
- self._directory = str(abs_directory)
- self.include_markdown = include_markdown
- self._lazy_files: list[FileInfo] | None = None
-
- # Use PathValidator for security validation
- self._validator = PathValidator(abs_directory)
- # Use DirectoryScanner for file discovery (use absolute path)
- self._scanner = DirectoryScanner(str(abs_directory), include_markdown)
-
- @property
- def directory(self) -> str:
- return self._directory
-
- def toggle_markdown(
- self, include_markdown: bool
- ) -> LazyListOfFilesAppFileRouter:
- # Only create a new instance if the include_markdown flag is different
- if include_markdown != self.include_markdown:
- return LazyListOfFilesAppFileRouter(
- self.directory, include_markdown
- )
- return self
-
- def mark_stale(self) -> None:
- self._lazy_files = None
-
- def register_temp_dir(self, temp_dir: str) -> None:
- """Register a temp directory as allowed for file access.
-
- Args:
- temp_dir: The absolute path to the temp directory to allow.
- """
- self._validator.register_temp_dir(temp_dir)
-
- def is_file_in_allowed_temp_dir(self, filepath: str) -> bool:
- """Check if a file is inside an allowed temp directory.
-
- Args:
- filepath: The file path to check.
-
- Returns:
- True if the file is in an allowed temp directory, False otherwise.
- """
- return self._validator.is_file_in_allowed_temp_dir(filepath)
-
- def get_file_manager(
- self,
- key: MarimoFileKey,
- defaults: AppDefaults | None = None,
- ) -> AppFileManager:
- """
- Given a key, return an AppFileManager.
-
- For directory sources, if the key is a relative path, resolve it
- relative to the source's directory. Absolute paths must be within
- the source's directory for security.
- """
- defaults = defaults or AppDefaults()
- resolved_path = self.resolve_file_path(key)
- if resolved_path is None:
- return AppFileManager(None, defaults=defaults)
- return AppFileManager(resolved_path, defaults=defaults)
-
- def resolve_file_path(self, key: MarimoFileKey) -> str | None:
- if key.startswith(AppFileRouter.NEW_FILE):
- return None
-
- directory = Path(self._directory)
- filepath = Path(key)
-
- # Resolve filepath for use
- # If filepath is relative, resolve it relative to directory
- if not filepath.is_absolute():
- filepath = directory / filepath
-
- # Use PathValidator for security validation
- # Check if file is in an allowed temp directory (e.g., for tutorials)
- # If so, skip the directory validation
- is_in_allowed_temp_dir = self._validator.is_file_in_allowed_temp_dir(
- str(filepath)
- )
-
- if not is_in_allowed_temp_dir:
- # Validate that filepath is inside directory
- self._validator.validate_inside_directory(directory, filepath)
-
- if filepath.exists():
- return str(filepath)
-
- raise HTTPException(
- status_code=HTTPStatus.NOT_FOUND,
- detail=f"File {key} not found",
- )
-
- @property
- def files(self) -> list[FileInfo]:
- if self._lazy_files is None:
- try:
- # Use DirectoryScanner to load files
- self._lazy_files = self._scanner.scan()
- except HTTPException as e:
- if e.status_code == HTTPStatus.REQUEST_TIMEOUT:
- # Return partial results on timeout
- LOGGER.warning(
- "Timeout during file scan, returning partial results"
- )
- self._lazy_files = self._scanner.partial_results
- else:
- raise
- return self._lazy_files
-
- def get_unique_file_key(self) -> str | None:
- return None
-
- def maybe_get_single_file(self) -> MarimoFile | None:
- return None
-
-
-# Count total marimo files (not directories)
-def count_files(file_list: list[FileInfo]) -> int:
- count = 0
- for item in file_list:
- if not item.is_directory:
- count += 1
- if item.children:
- count += count_files(item.children)
- return count
-
-
-def flatten_files(files: list[FileInfo]) -> Iterator[FileInfo]:
- """Iterate over files, skipping directories."""
- stack = files.copy()
- while stack:
- file = stack.pop()
- if file.is_directory:
- stack.extend(file.children)
- else:
- yield file
diff --git a/marimo/_server/resume_strategies.py b/marimo/_server/resume_strategies.py
index 3943691415..1996339cf6 100644
--- a/marimo/_server/resume_strategies.py
+++ b/marimo/_server/resume_strategies.py
@@ -17,7 +17,7 @@ from marimo._types.ids import SessionId
LOGGER = _loggers.marimo_logger()
if TYPE_CHECKING:
- from marimo._server.file_router import MarimoFileKey
+ from marimo._server.workspace import MarimoFileKey
class SessionResumeStrategy(Protocol):
diff --git a/marimo/_server/rtc/doc.py b/marimo/_server/rtc/doc.py
index 277b6c16f1..7165f6bad6 100644
--- a/marimo/_server/rtc/doc.py
+++ b/marimo/_server/rtc/doc.py
@@ -5,7 +5,7 @@ import asyncio
from typing import TYPE_CHECKING
from marimo import _loggers
-from marimo._server.file_router import MarimoFileKey
+from marimo._server.workspace import MarimoFileKey
from marimo._types.ids import CellId_t
if TYPE_CHECKING:
diff --git a/marimo/_server/session_manager.py b/marimo/_server/session_manager.py
index 8ccfa66190..3c115d659d 100644
--- a/marimo/_server/session_manager.py
+++ b/marimo/_server/session_manager.py
@@ -20,17 +20,18 @@ from marimo._runtime.commands import (
SerializedQueryParams,
)
from marimo._server.app_defaults import AppDefaults
-from marimo._server.file_router import (
- AppFileRouter,
- MarimoFileKey,
- flatten_files,
-)
from marimo._server.lsp import LspServer
from marimo._server.recents import RecentFilesManager
from marimo._server.resume_strategies import create_resume_strategy
from marimo._server.session.listeners import RecentsTrackerListener
from marimo._server.token_manager import TokenManager
from marimo._server.tokens import AuthToken, SkewProtectionToken
+from marimo._server.workspace import (
+ NEW_FILE,
+ MarimoFileKey,
+ NotebookWorkspace,
+ flatten_files,
+)
from marimo._session.app_host import AppHostContext, AppHostPool
from marimo._session.consumer import SessionConsumer
from marimo._session.events import SessionEventBus
@@ -70,7 +71,7 @@ class SessionManager:
def __init__(
self,
*,
- file_router: AppFileRouter,
+ workspace: NotebookWorkspace,
mode: SessionMode,
quiet: bool,
include_code: bool,
@@ -86,7 +87,7 @@ class SessionManager:
isolate_apps: bool = False,
) -> None:
# Core configuration
- self.file_router = file_router
+ self.workspace = workspace
self.mode = mode
self.quiet = quiet
self.include_code = include_code
@@ -111,11 +112,11 @@ class SessionManager:
def _get_code() -> str:
defaults = AppDefaults.from_config_manager(config_manager)
- if file_router.get_unique_file_key() is not None:
- app = file_router.get_single_app_file_manager(defaults).app
+ if workspace.get_unique_file_key() is not None:
+ app = workspace.get_single_app_file_manager(defaults).app
return "".join(code for code in app.cell_manager.codes())
- files = list(flatten_files(file_router.files))
+ files = list(flatten_files(workspace.files))
entries = [
f"{file.path}:{file.last_modified or 0.0}"
for file in files
@@ -161,11 +162,9 @@ class SessionManager:
def app_manager(self, key: MarimoFileKey) -> AppFileManager:
"""Get the app manager for the given key."""
defaults = AppDefaults.from_config_manager(self._config_manager)
- if self.mode is SessionMode.EDIT and not key.startswith(
- AppFileRouter.NEW_FILE
- ):
- self.file_router.register_allowed_file(key)
- return self.file_router.get_file_manager(key, defaults)
+ if self.mode is SessionMode.EDIT and not key.startswith(NEW_FILE):
+ self.workspace.register_allowed_path(key)
+ return self.workspace.load(key, defaults)
def create_session(
self,
@@ -185,13 +184,9 @@ class SessionManager:
# Get app file manager
defaults = AppDefaults.from_config_manager(self._config_manager)
- if self.mode is SessionMode.EDIT and not file_key.startswith(
- AppFileRouter.NEW_FILE
- ):
- self.file_router.register_allowed_file(file_key)
- app_file_manager = self.file_router.get_file_manager(
- file_key, defaults
- )
+ if self.mode is SessionMode.EDIT and not file_key.startswith(NEW_FILE):
+ self.workspace.register_allowed_path(file_key)
+ app_file_manager = self.workspace.load(file_key, defaults)
# Create the session
from marimo._runtime.commands import AppMetadata
@@ -356,7 +351,7 @@ class SessionManager:
def any_clients_connected(self, key: MarimoFileKey) -> bool:
"""Returns True if at least one client has an open socket."""
- if key.startswith(AppFileRouter.NEW_FILE):
+ if key.startswith(NEW_FILE):
return False
sessions_for_file = self._repository.get_by_file_path(key)
diff --git a/marimo/_server/start.py b/marimo/_server/start.py
index 36a18df6fb..711bd18311 100644
--- a/marimo/_server/start.py
+++ b/marimo/_server/start.py
@@ -22,10 +22,6 @@ from marimo._server.api import lifespans
from marimo._server.config import (
StarletteServerStateInit,
)
-from marimo._server.file_router import (
- AppFileRouter,
- LazyListOfFilesAppFileRouter,
-)
from marimo._server.lsp import CompositeLspServer, NoopLspServer
from marimo._server.main import create_starlette_app
from marimo._server.registry import LIFESPAN_REGISTRY
@@ -36,6 +32,10 @@ from marimo._server.utils import (
initialize_fd_limit,
)
from marimo._server.uvicorn_utils import initialize_signals
+from marimo._server.workspace import (
+ DirectoryWorkspace,
+ NotebookWorkspace,
+)
from marimo._session.model import SessionMode
from marimo._tracer import LOGGER
from marimo._utils.lifespans import Lifespans
@@ -187,7 +187,7 @@ def _resolve_proxy(port: int, host: str, proxy: str | None) -> tuple[int, str]:
def start(
*,
- file_router: AppFileRouter,
+ workspace: NotebookWorkspace,
mode: SessionMode,
development_mode: bool,
quiet: bool,
@@ -250,9 +250,9 @@ def start(
# This is the path that will be used to read the project configuration
start_path: str | None = None
- if (single_file := file_router.maybe_get_single_file()) is not None:
+ if (single_file := workspace.single_file()) is not None:
start_path = single_file.path
- elif (directory := file_router.directory) is not None:
+ elif (directory := workspace.directory) is not None:
start_path = directory
else:
start_path = os.getcwd()
@@ -272,7 +272,7 @@ def start(
if (
mode == SessionMode.RUN
and watch
- and isinstance(file_router, LazyListOfFilesAppFileRouter)
+ and isinstance(workspace, DirectoryWorkspace)
):
LOGGER.warning(
"Using `marimo run <folder> --watch`: gallery files are "
@@ -293,7 +293,7 @@ def start(
}
)
- is_multi = file_router.get_unique_file_key() is None
+ is_multi = workspace.get_unique_file_key() is None
isolate_apps = is_multi and config_reader.experimental.get(
"isolate_apps", False
)
@@ -308,7 +308,7 @@ def start(
)
session_manager = SessionManager(
- file_router=file_router,
+ workspace=workspace,
mode=mode,
quiet=quiet,
include_code=include_code,
diff --git a/marimo/_server/workspace/__init__.py b/marimo/_server/workspace/__init__.py
new file mode 100644
index 0000000000..68dc8c90ce
--- /dev/null
+++ b/marimo/_server/workspace/__init__.py
@@ -0,0 +1,58 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Server-side notebook workspace abstractions.
+
+A :class:`NotebookWorkspace` represents the set of notebooks a server is
+hosting. Concrete subclasses cover:
+
+- :class:`EmptyWorkspace` — untitled (``__new__``) notebook
+- :class:`SingleFileWorkspace` — single notebook (``marimo edit nb.py``)
+- :class:`FixedFilesWorkspace` — fixed allowlist (``marimo run a.py b.py``)
+- :class:`DirectoryWorkspace` — lazy directory scan (``marimo edit ./``)
+"""
+
+import os
+
+from marimo import _loggers
+from marimo._server.workspace._base import (
+ NEW_FILE,
+ MarimoFileKey,
+ NotebookWorkspace,
+ count_files,
+ flatten_files,
+)
+from marimo._server.workspace._directory import DirectoryWorkspace
+from marimo._server.workspace._empty import EmptyWorkspace
+from marimo._server.workspace._fixed import FixedFilesWorkspace
+from marimo._server.workspace._single import SingleFileWorkspace
+from marimo._utils.http import HTTPException, HTTPStatus
+from marimo._utils.marimo_path import MarimoPath
+
+LOGGER = _loggers.marimo_logger()
+
+
+def infer_workspace(path: str) -> NotebookWorkspace:
+ """Pick a concrete workspace for a user-supplied file or directory path."""
+ if os.path.isfile(path):
+ LOGGER.debug("Routing to file %s", path)
+ return SingleFileWorkspace.from_path(MarimoPath(path))
+ if os.path.isdir(path):
+ LOGGER.debug("Routing to directory %s", path)
+ return DirectoryWorkspace(path, include_markdown=False)
+ raise HTTPException(
+ status_code=HTTPStatus.BAD_REQUEST,
+ detail=f"Path {path} is not a valid file or directory",
+ )
+
+
+__all__ = [
+ "NEW_FILE",
+ "DirectoryWorkspace",
+ "EmptyWorkspace",
+ "FixedFilesWorkspace",
+ "MarimoFileKey",
+ "NotebookWorkspace",
+ "SingleFileWorkspace",
+ "count_files",
+ "flatten_files",
+ "infer_workspace",
+]
diff --git a/marimo/_server/workspace/_base.py b/marimo/_server/workspace/_base.py
new file mode 100644
index 0000000000..1afb8cd354
--- /dev/null
+++ b/marimo/_server/workspace/_base.py
@@ -0,0 +1,167 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Abstract base class for server-side notebook workspaces."""
+
+from __future__ import annotations
+
+import abc
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from marimo._server.app_defaults import AppDefaults
+from marimo._session.notebook import AppFileManager
+from marimo._utils.http import HTTPException, HTTPStatus
+from marimo._utils.marimo_path import MarimoPath
+from marimo._utils.paths import normalize_path
+
+if TYPE_CHECKING:
+ from collections.abc import Iterator
+
+ from marimo._server.models.files import FileInfo
+ from marimo._server.models.home import MarimoFile
+
+# Wire-format key for an untitled notebook. The string boundary is preserved
+# for HTTP query params and session initialization IDs.
+NEW_FILE: str = "__new__"
+
+# Some unique identifier for a file. Phase 3 will replace this with a tagged
+# union (NewFileKey | PathFileKey).
+MarimoFileKey = str
+
+
+class NotebookWorkspace(abc.ABC):
+ """A server-side abstraction for the set of notebooks a server is hosting.
+
+ Owned by ``SessionManager``. Handles workspace browsing, allowlisting, lazy
+ directory scanning, and security validation.
+ """
+
+ @property
+ def directory(self) -> str | None:
+ """The root directory of this workspace, if any."""
+ return None
+
+ @property
+ @abc.abstractmethod
+ def files(self) -> list[FileInfo]:
+ """All files in this workspace as a recursive tree."""
+
+ @abc.abstractmethod
+ def single_file(self) -> MarimoFile | None:
+ """If this workspace represents a single notebook, return it."""
+
+ @abc.abstractmethod
+ def get_unique_file_key(self) -> MarimoFileKey | None:
+ """The unique file key for this workspace, if any."""
+
+ @abc.abstractmethod
+ def resolve(self, key: MarimoFileKey) -> str | None:
+ """Resolve a key to an absolute path; ``None`` for new files.
+
+ Useful for endpoints that need file-backed resources (e.g. thumbnails)
+ without the overhead of parsing/loading a notebook.
+ """
+
+ def load(
+ self,
+ key: MarimoFileKey,
+ defaults: AppDefaults | None = None,
+ ) -> AppFileManager:
+ """Load the notebook for the given key into an ``AppFileManager``.
+
+ Built on top of :meth:`resolve` — subclasses customize ``resolve`` and
+ inherit the right ``load`` semantics for free.
+ """
+ defaults = defaults or AppDefaults()
+ resolved = self.resolve(key)
+ if resolved is None:
+ return AppFileManager(None, defaults=defaults)
+ return AppFileManager(resolved, defaults=defaults)
+
+ def get_single_app_file_manager(
+ self,
+ defaults: AppDefaults | None = None,
+ ) -> AppFileManager:
+ """Convenience for workspaces with a unique single file."""
+ key = self.get_unique_file_key()
+ assert key is not None, "Expected a single file"
+ return self.load(key, defaults)
+
+ # Optional capabilities — subclasses override only when supported.
+
+ def register_allowed_path(self, path: str) -> None:
+ """Allow a file path that wasn't part of the original collection.
+
+ No-op by default. ``SingleFileWorkspace`` overrides to extend its
+ allowlist for files created at runtime.
+ """
+ del path
+
+ def register_temp_dir(self, temp_dir: str) -> None:
+ """Register a temp directory as allowed for file access.
+
+ No-op by default. ``DirectoryWorkspace`` overrides for tutorial
+ support.
+ """
+ del temp_dir
+
+ def is_in_allowed_temp_dir(self, path: str) -> bool:
+ """Whether ``path`` lives inside an allowed temp directory.
+
+ Returns ``False`` by default. ``DirectoryWorkspace`` overrides.
+ """
+ del path
+ return False
+
+ def invalidate(self) -> None: # noqa: B027 — intentional no-op default
+ """Invalidate any cached listing.
+
+ No-op by default. ``DirectoryWorkspace`` overrides.
+ """
+
+ def set_include_markdown(self, include_markdown: bool) -> None:
+ """Toggle markdown inclusion in directory listings.
+
+ No-op by default. ``DirectoryWorkspace`` overrides — mutates in
+ place.
+ """
+ del include_markdown
+
+
+def file_not_found(key: MarimoFileKey) -> HTTPException:
+ """Build the standard 404 response for an unresolvable file key."""
+ return HTTPException(
+ status_code=HTTPStatus.NOT_FOUND,
+ detail=f"File {key} not found",
+ )
+
+
+def normalize_allowlist_entry(path: str) -> str:
+ """Canonicalize a path for storage in or lookup against an allowlist.
+
+ Resolves the path to absolute form (validating it as a marimo source file)
+ and applies our standard normalization. Allowlist entries and lookup keys
+ must run through this same pipeline to match.
+ """
+ return str(normalize_path(Path(MarimoPath(path).absolute_name)))
+
+
+def count_files(file_list: list[FileInfo]) -> int:
+ """Count notebook files (not directories) in a recursive tree."""
+ count = 0
+ for item in file_list:
+ if not item.is_directory:
+ count += 1
+ if item.children:
+ count += count_files(item.children)
+ return count
+
+
+def flatten_files(files: list[FileInfo]) -> Iterator[FileInfo]:
+ """Iterate over files, skipping directories."""
+ stack = files.copy()
+ while stack:
+ file = stack.pop()
+ if file.is_directory:
+ stack.extend(file.children)
+ else:
+ yield file
diff --git a/marimo/_server/workspace/_directory.py b/marimo/_server/workspace/_directory.py
new file mode 100644
index 0000000000..b77b5ada50
--- /dev/null
+++ b/marimo/_server/workspace/_directory.py
@@ -0,0 +1,108 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Workspace that lazily scans a directory of notebooks."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from marimo import _loggers
+from marimo._server.files.directory_scanner import DirectoryScanner
+from marimo._server.files.path_validator import PathValidator
+from marimo._server.workspace._base import (
+ NEW_FILE,
+ MarimoFileKey,
+ NotebookWorkspace,
+ file_not_found,
+)
+from marimo._utils.http import HTTPException, HTTPStatus
+
+if TYPE_CHECKING:
+ from marimo._server.models.files import FileInfo
+ from marimo._server.models.home import MarimoFile
+
+LOGGER = _loggers.marimo_logger()
+
+
+class DirectoryWorkspace(NotebookWorkspace):
+ """A workspace backed by a directory, scanned lazily on demand.
+
+ Used by ``marimo edit ./`` and ``marimo run ./``. File access is validated
+ via :class:`PathValidator` to ensure paths stay within the directory (or an
+ explicitly registered temp directory).
+ """
+
+ def __init__(self, directory: str, include_markdown: bool) -> None:
+ # Make absolute but don't resolve symlinks — preserve user paths.
+ abs_directory = Path(directory).absolute()
+ self._directory = str(abs_directory)
+ self._include_markdown = include_markdown
+ self._lazy_files: list[FileInfo] | None = None
+ self._validator = PathValidator(abs_directory)
+ self._scanner = DirectoryScanner(str(abs_directory), include_markdown)
+
+ @property
+ def directory(self) -> str:
+ return self._directory
+
+ @property
+ def include_markdown(self) -> bool:
+ return self._include_markdown
+
+ def set_include_markdown(self, include_markdown: bool) -> None:
+ """Toggle markdown inclusion in place; rescans on next access."""
+ if include_markdown == self._include_markdown:
+ return
+ self._include_markdown = include_markdown
+ self._scanner = DirectoryScanner(self._directory, include_markdown)
+ self._lazy_files = None
+
+ def invalidate(self) -> None:
+ self._lazy_files = None
+
+ def register_temp_dir(self, temp_dir: str) -> None:
+ self._validator.register_temp_dir(temp_dir)
+
+ def is_in_allowed_temp_dir(self, path: str) -> bool:
+ return self._validator.is_file_in_allowed_temp_dir(path)
+
+ def single_file(self) -> MarimoFile | None:
+ return None
+
+ def get_unique_file_key(self) -> MarimoFileKey | None:
+ return None
+
+ def resolve(self, key: MarimoFileKey) -> str | None:
+ if key.startswith(NEW_FILE):
+ return None
+
+ directory = Path(self._directory)
+ filepath = Path(key)
+
+ # Resolve relative paths against the workspace directory.
+ if not filepath.is_absolute():
+ filepath = directory / filepath
+
+ # Tutorial files live in registered temp dirs and bypass containment.
+ if not self._validator.is_file_in_allowed_temp_dir(str(filepath)):
+ self._validator.validate_inside_directory(directory, filepath)
+
+ if filepath.exists():
+ return str(filepath)
+
+ raise file_not_found(key)
+
+ @property
+ def files(self) -> list[FileInfo]:
+ if self._lazy_files is None:
+ try:
+ self._lazy_files = self._scanner.scan()
+ except HTTPException as e:
+ if e.status_code == HTTPStatus.REQUEST_TIMEOUT:
+ LOGGER.warning(
+ "Timeout during file scan, returning partial results"
+ )
+ self._lazy_files = self._scanner.partial_results
+ else:
+ raise
+ return self._lazy_files
diff --git a/marimo/_server/workspace/_empty.py b/marimo/_server/workspace/_empty.py
new file mode 100644
index 0000000000..2391fef6eb
--- /dev/null
+++ b/marimo/_server/workspace/_empty.py
@@ -0,0 +1,50 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Workspace for an untitled (new) notebook."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from marimo._server.workspace._base import (
+ NEW_FILE,
+ MarimoFileKey,
+ NotebookWorkspace,
+ file_not_found,
+)
+from marimo._utils.paths import normalize_path
+
+if TYPE_CHECKING:
+ from marimo._server.models.files import FileInfo
+ from marimo._server.models.home import MarimoFile
+
+
+class EmptyWorkspace(NotebookWorkspace):
+ """An empty (untitled) workspace, used by ``marimo new``.
+
+ The workspace key is the ``__new__`` sentinel; concrete file paths are
+ accepted as a fallback so that callers which bootstrap with
+ ``EmptyWorkspace`` and later open a real file (e.g. via the homepage)
+ continue to work.
+ """
+
+ def get_unique_file_key(self) -> MarimoFileKey | None:
+ return NEW_FILE
+
+ def single_file(self) -> MarimoFile | None:
+ return None
+
+ @property
+ def files(self) -> list[FileInfo]:
+ return []
+
+ def resolve(self, key: MarimoFileKey) -> str | None:
+ if key.startswith(NEW_FILE):
+ return None
+ if os.path.exists(key):
+ # Match sibling workspaces: return an absolute normalized path so
+ # downstream comparisons (e.g. session lookups) don't trip on
+ # relative-vs-absolute mismatches.
+ return str(normalize_path(Path(key)))
+ raise file_not_found(key)
diff --git a/marimo/_server/workspace/_fixed.py b/marimo/_server/workspace/_fixed.py
new file mode 100644
index 0000000000..aab60798a4
--- /dev/null
+++ b/marimo/_server/workspace/_fixed.py
@@ -0,0 +1,80 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Workspace for a fixed list of notebooks (``marimo run a.py b.py``)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from marimo._server.models.files import FileInfo
+from marimo._server.workspace._base import (
+ NEW_FILE,
+ MarimoFileKey,
+ NotebookWorkspace,
+ file_not_found,
+ normalize_allowlist_entry,
+)
+from marimo._utils.paths import normalize_path
+
+if TYPE_CHECKING:
+ from marimo._server.models.home import MarimoFile
+
+
+class FixedFilesWorkspace(NotebookWorkspace):
+ """A workspace pointing at a fixed allowlist of notebooks.
+
+ Used by ``marimo run a.py b.py`` and ``marimo run dir/`` snapshots. The
+ allowlist is set at construction time and never grows.
+ """
+
+ def __init__(
+ self,
+ files: list[MarimoFile],
+ directory: str | None = None,
+ ) -> None:
+ self._files = files
+ self._directory = directory
+ self._allowed_paths = {
+ normalize_allowlist_entry(file.path) for file in files
+ }
+
+ @property
+ def directory(self) -> str | None:
+ return self._directory
+
+ @property
+ def files(self) -> list[FileInfo]:
+ return [
+ FileInfo(
+ id=file.path,
+ name=file.name,
+ path=file.path,
+ last_modified=file.last_modified,
+ is_directory=False,
+ is_marimo_file=True,
+ )
+ for file in self._files
+ ]
+
+ def single_file(self) -> MarimoFile | None:
+ return None
+
+ def get_unique_file_key(self) -> MarimoFileKey | None:
+ return None
+
+ def resolve(self, key: MarimoFileKey) -> str | None:
+ if key.startswith(NEW_FILE):
+ raise file_not_found(key)
+
+ filepath = Path(key)
+ if not filepath.is_absolute() and self._directory:
+ filepath = Path(self._directory) / filepath
+ normalized_path = normalize_path(filepath)
+ absolute_path = str(normalized_path)
+ if absolute_path not in self._allowed_paths:
+ raise file_not_found(key)
+
+ if normalized_path.exists():
+ return absolute_path
+
+ raise file_not_found(key)
diff --git a/marimo/_server/workspace/_single.py b/marimo/_server/workspace/_single.py
new file mode 100644
index 0000000000..ff9325dcb2
--- /dev/null
+++ b/marimo/_server/workspace/_single.py
@@ -0,0 +1,91 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Workspace for a single notebook (``marimo edit nb.py``)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from marimo._server.models.home import MarimoFile
+from marimo._server.workspace._base import (
+ NEW_FILE,
+ MarimoFileKey,
+ NotebookWorkspace,
+ file_not_found,
+ normalize_allowlist_entry,
+)
+from marimo._utils.marimo_path import MarimoPath
+from marimo._utils.paths import normalize_path
+
+if TYPE_CHECKING:
+ from marimo._server.models.files import FileInfo
+
+
+class SingleFileWorkspace(NotebookWorkspace):
+ """A workspace pointing at a single notebook.
+
+ Used by ``marimo edit nb.py`` and ``marimo run nb.py``. In edit mode the
+ allowlist can grow at runtime (via ``register_allowed_path``) to support
+ notebooks created during the session.
+ """
+
+ def __init__(self, file: MarimoFile) -> None:
+ self._file = file
+ self._allowed_paths = {normalize_allowlist_entry(file.path)}
+
+ @staticmethod
+ def from_path(file: MarimoPath) -> SingleFileWorkspace:
+ """Build a workspace from a validated marimo path."""
+ return SingleFileWorkspace(
+ MarimoFile(
+ name=file.relative_name,
+ path=file.absolute_name,
+ last_modified=file.last_modified,
+ )
+ )
+
+ @property
+ def files(self) -> list[FileInfo]:
+ from marimo._server.models.files import FileInfo
+
+ return [
+ FileInfo(
+ id=self._file.path,
+ name=self._file.name,
+ path=self._file.path,
+ last_modified=self._file.last_modified,
+ is_directory=False,
+ is_marimo_file=True,
+ )
+ ]
+
+ def single_file(self) -> MarimoFile | None:
+ return self._file
+
+ def get_unique_file_key(self) -> MarimoFileKey | None:
+ return self._file.path
+
+ def resolve(self, key: MarimoFileKey) -> str | None:
+ if key.startswith(NEW_FILE):
+ return None
+
+ filepath = Path(key)
+ normalized_path = normalize_path(filepath)
+ absolute_path = str(normalized_path)
+ if absolute_path not in self._allowed_paths:
+ raise file_not_found(key)
+
+ if normalized_path.exists():
+ return absolute_path
+
+ raise file_not_found(key)
+
+ def register_allowed_path(self, path: str) -> None:
+ """Extend the allowlist for files created at runtime.
+
+ Always extends, unconditionally — ``SingleFileWorkspace`` represents
+ single-file edit mode, where the user can branch off into new
+ notebooks created by the kernel. The fixed-allowlist behavior of
+ :class:`FixedFilesWorkspace` is the read-only counterpart.
+ """
+ self._allowed_paths.add(normalize_allowlist_entry(path))
diff --git a/marimo/_session/session_repository.py b/marimo/_session/session_repository.py
index 0b4db898d3..65a3565a94 100644
--- a/marimo/_session/session_repository.py
+++ b/marimo/_session/session_repository.py
@@ -13,7 +13,7 @@ from marimo._types.ids import ConsumerId, SessionId
if TYPE_CHECKING:
from collections.abc import Mapping
- from marimo._server.file_router import MarimoFileKey
+ from marimo._server.workspace import MarimoFileKey
class SessionRepository:
diff --git a/tests/_cli/test_cli.py b/tests/_cli/test_cli.py
index 4a1ed1aed9..bd02b21a95 100644
--- a/tests/_cli/test_cli.py
+++ b/tests/_cli/test_cli.py
@@ -29,16 +29,16 @@ from marimo._ast import codegen
from marimo._ast.cell import CellConfig
from marimo._cli.cli import (
_collect_marimo_files,
- _create_run_file_router,
+ _create_run_workspace,
main as cli_main,
)
from marimo._config.manager import get_default_config_manager
from marimo._dependencies.dependencies import DependencyManager
-from marimo._server.file_router import (
- LazyListOfFilesAppFileRouter,
- ListOfFilesAppFileRouter,
-)
from marimo._server.templates.templates import get_version
+from marimo._server.workspace import (
+ DirectoryWorkspace,
+ FixedFilesWorkspace,
+)
from marimo._utils.platform import is_windows
from marimo._utils.toml import toml_reader
@@ -1173,30 +1173,30 @@ def test_collect_marimo_files_excludes_marimo_generated_markdown(
assert str(generated_md) not in paths
-def test_create_run_file_router_watch_single_directory_is_lazy(
+def test_create_run_workspace_watch_single_directory_is_lazy(
tmp_path: Path,
) -> None:
(tmp_path / "one.py").write_text(
"import marimo\napp = marimo.App()\n", encoding="utf-8"
)
- router = _create_run_file_router([str(tmp_path)], watch=True)
- assert isinstance(router, LazyListOfFilesAppFileRouter)
- assert router.include_markdown is True
+ workspace = _create_run_workspace([str(tmp_path)], watch=True)
+ assert isinstance(workspace, DirectoryWorkspace)
+ assert workspace.include_markdown is True
-def test_create_run_file_router_no_watch_single_directory_is_static(
+def test_create_run_workspace_no_watch_single_directory_is_static(
tmp_path: Path,
) -> None:
(tmp_path / "one.py").write_text(
"import marimo\napp = marimo.App()\n", encoding="utf-8"
)
- router = _create_run_file_router([str(tmp_path)], watch=False)
- assert isinstance(router, ListOfFilesAppFileRouter)
+ workspace = _create_run_workspace([str(tmp_path)], watch=False)
+ assert isinstance(workspace, FixedFilesWorkspace)
-def test_create_run_file_router_watch_mixed_paths_is_static(
+def test_create_run_workspace_watch_mixed_paths_is_static(
tmp_path: Path,
) -> None:
directory = tmp_path / "gallery"
@@ -1209,10 +1209,10 @@ def test_create_run_file_router_watch_mixed_paths_is_static(
"import marimo\napp = marimo.App()\n", encoding="utf-8"
)
- router = _create_run_file_router(
+ workspace = _create_run_workspace(
[str(directory), str(standalone)], watch=True
)
- assert isinstance(router, ListOfFilesAppFileRouter)
+ assert isinstance(workspace, FixedFilesWorkspace)
def test_cli_run_with_show_code(temp_marimo_file: str) -> None:
diff --git a/tests/_server/api/endpoints/test_assets.py b/tests/_server/api/endpoints/test_assets.py
index 4e48789eef..065263fa12 100644
--- a/tests/_server/api/endpoints/test_assets.py
+++ b/tests/_server/api/endpoints/test_assets.py
@@ -14,13 +14,18 @@ from marimo._server.api.endpoints.assets import (
_inject_service_worker,
)
from marimo._server.api.utils import parse_title
-from marimo._server.file_router import AppFileRouter
+from marimo._server.workspace import (
+ DirectoryWorkspace,
+ EmptyWorkspace,
+ FixedFilesWorkspace,
+ SingleFileWorkspace,
+)
from marimo._session.model import SessionMode
from marimo._utils.marimo_path import MarimoPath
from tests._server.mocks import (
- file_router_scope,
token_header,
- with_file_router,
+ with_workspace,
+ workspace_scope,
)
if TYPE_CHECKING:
@@ -39,7 +44,7 @@ def test_index(client: TestClient) -> None:
response = client.get("/", headers=token_header())
assert response.status_code == 200, response.text
content = response.text
- filename = session_manager.file_router.get_unique_file_key()
+ filename = session_manager.workspace.get_unique_file_key()
title = parse_title(filename)
assert f"<marimo-filename hidden>{filename}</marimo-filename>" in content
assert filename is not None
@@ -51,7 +56,7 @@ def test_index(client: TestClient) -> None:
assert "public-files-sw.js" in content
-@with_file_router(AppFileRouter.from_files([]))
+@with_workspace(FixedFilesWorkspace([]))
def test_index_when_empty(client: TestClient) -> None:
# Login page
response = client.get("/") # no header
@@ -67,7 +72,7 @@ def test_index_when_empty(client: TestClient) -> None:
assert "<title>marimo</title>" in content
-@with_file_router(AppFileRouter.new_file())
+@with_workspace(EmptyWorkspace())
def test_index_when_new_file(client: TestClient) -> None:
# Login page
response = client.get("/") # no header
@@ -206,8 +211,8 @@ def test_index_response_has_security_headers(client: TestClient) -> None:
def test_index_with_directory(client: TestClient, tmp_path: Path) -> None:
- with file_router_scope(
- client, AppFileRouter.from_directory(str(tmp_path))
+ with workspace_scope(
+ client, DirectoryWorkspace(str(tmp_path), include_markdown=False)
):
response = client.get("/", headers=token_header())
assert response.status_code == 200, response.text
@@ -223,8 +228,8 @@ def test_index_with_directory_run_mode(
app_state = AppState.from_app(cast(Any, client.app))
app_state.session_manager.mode = SessionMode.RUN
- with file_router_scope(
- client, AppFileRouter.from_directory(str(tmp_path))
+ with workspace_scope(
+ client, DirectoryWorkspace(str(tmp_path), include_markdown=False)
):
response = client.get("/", headers=token_header())
assert response.status_code == 200, response.text
@@ -398,7 +403,7 @@ def test_vfile_download_query_param_sets_content_disposition(
def test_public_file_serving(client: TestClient) -> None:
# Setup app state with a mock notebook
app_state = AppState.from_app(cast(Any, client.app))
- file_key = app_state.session_manager.file_router.get_unique_file_key()
+ file_key = app_state.session_manager.workspace.get_unique_file_key()
assert file_key is not None
assert file_key.endswith(".py")
@@ -438,7 +443,7 @@ def test_service_worker(client: TestClient) -> None:
def test_public_file_security(client: TestClient) -> None:
# Setup app state
app_state = AppState.from_app(cast(Any, client.app))
- file_key = app_state.session_manager.file_router.get_unique_file_key()
+ file_key = app_state.session_manager.workspace.get_unique_file_key()
assert file_key is not None
assert file_key.endswith(".py")
@@ -615,8 +620,8 @@ def test_index_lsp_workspace_with_filename(
notebook_file = subdir.joinpath("notebook.py")
notebook_file.touch()
- with file_router_scope(
- client, AppFileRouter.from_filename(MarimoPath(notebook_file))
+ with workspace_scope(
+ client, SingleFileWorkspace.from_path(MarimoPath(notebook_file))
):
response = client.get("/", headers=token_header())
root_uri = json.dumps(temp_project_dir.as_uri())
@@ -631,8 +636,9 @@ def test_index_lsp_workspace_with_root_directory(
temp_project_dir = tmp_path
temp_project_dir.joinpath("pyproject.toml").touch()
- with file_router_scope(
- client, AppFileRouter.from_directory(str(temp_project_dir))
+ with workspace_scope(
+ client,
+ DirectoryWorkspace(str(temp_project_dir), include_markdown=False),
):
response = client.get("/?file=__new__file.py", headers=token_header())
root_path = temp_project_dir
@@ -651,7 +657,9 @@ def test_index_lsp_workspace_with_sub_directory(
subdir = temp_project_dir.joinpath("subdir")
subdir.mkdir()
- with file_router_scope(client, AppFileRouter.from_directory(str(subdir))):
+ with workspace_scope(
+ client, DirectoryWorkspace(str(subdir), include_markdown=False)
+ ):
response = client.get("/?file=__new__file.py", headers=token_header())
root_path = temp_project_dir
root_uri = json.dumps(root_path.as_uri())
@@ -661,7 +669,7 @@ def test_index_lsp_workspace_with_sub_directory(
assert f'"documentUri": {document_uri}' in response.text
-@with_file_router(AppFileRouter.new_file())
+@with_workspace(EmptyWorkspace())
def test_index_lsp_workspace_fallback_to_cwd(client: TestClient) -> None:
response = client.get("/", headers=token_header())
root_path = Path.cwd()
diff --git a/tests/_server/api/endpoints/test_file_explorer.py b/tests/_server/api/endpoints/test_file_explorer.py
index e21d07ae73..8e954b0ddc 100644
--- a/tests/_server/api/endpoints/test_file_explorer.py
+++ b/tests/_server/api/endpoints/test_file_explorer.py
@@ -122,7 +122,7 @@ def test_update_file_with_session(client: TestClient) -> None:
# Enable watch mode (file watcher is set up automatically)
sm.watch = True
- file_path = sm.file_router.get_unique_file_key()
+ file_path = sm.workspace.get_unique_file_key()
assert file_path
file_path = Path(file_path)
assert file_path.exists()
diff --git a/tests/_server/api/endpoints/test_files.py b/tests/_server/api/endpoints/test_files.py
index 95b83576a5..ade1c754da 100644
--- a/tests/_server/api/endpoints/test_files.py
+++ b/tests/_server/api/endpoints/test_files.py
@@ -37,7 +37,7 @@ HEADERS = {
def test_rename(client: TestClient) -> None:
current_filename = get_session_manager(
client
- ).file_router.get_unique_file_key()
+ ).workspace.get_unique_file_key()
assert current_filename
current_path = Path(current_filename)
@@ -103,7 +103,7 @@ def test_read_code_in_run_mode_without_include_code(
@pytest.mark.flaky(reruns=5)
@with_session(SESSION_ID)
def test_save_file(client: TestClient) -> None:
- filename = get_session_manager(client).file_router.get_unique_file_key()
+ filename = get_session_manager(client).workspace.get_unique_file_key()
assert filename
path = Path(filename)
@@ -157,7 +157,7 @@ def test_save_file(client: TestClient) -> None:
)
@with_session(SESSION_ID)
def test_save_with_header(client: TestClient) -> None:
- filename = get_session_manager(client).file_router.get_unique_file_key()
+ filename = get_session_manager(client).workspace.get_unique_file_key()
assert filename
path = Path(filename)
assert path.exists()
@@ -208,7 +208,7 @@ def test_save_with_header(client: TestClient) -> None:
@pytest.mark.flaky(reruns=5)
@with_session(SESSION_ID)
def test_save_with_invalid_file(client: TestClient) -> None:
- filename = get_session_manager(client).file_router.get_unique_file_key()
+ filename = get_session_manager(client).workspace.get_unique_file_key()
assert filename
path = Path(filename)
assert path.exists()
@@ -286,7 +286,7 @@ def test_save_file_cannot_rename(client: TestClient) -> None:
@pytest.mark.flaky(reruns=5)
@with_session(SESSION_ID)
def test_save_app_config(client: TestClient) -> None:
- filename = get_session_manager(client).file_router.get_unique_file_key()
+ filename = get_session_manager(client).workspace.get_unique_file_key()
assert filename
path = Path(filename)
@@ -315,7 +315,7 @@ def test_save_app_config(client: TestClient) -> None:
@with_session(SESSION_ID)
def test_copy_file(client: TestClient) -> None:
- filename = get_session_manager(client).file_router.get_unique_file_key()
+ filename = get_session_manager(client).workspace.get_unique_file_key()
assert filename
path = Path(filename)
assert path.exists()
@@ -346,18 +346,18 @@ def test_copy_file(client: TestClient) -> None:
@with_session(SESSION_ID)
def test_copy_file_with_relative_paths(client: TestClient) -> None:
- """Test that copy works with relative paths when file_router has a directory."""
- filename = get_session_manager(client).file_router.get_unique_file_key()
+ """Test that copy works with relative paths when workspace has a directory."""
+ filename = get_session_manager(client).workspace.get_unique_file_key()
assert filename
path = Path(filename)
assert path.exists()
file_contents = path.read_text()
assert "import marimo as mo" in file_contents
- # Get the directory and mock the file_router.directory property to simulate
+ # Get the directory and mock the workspace.directory property to simulate
# running from a subdirectory (marimo edit foo/dir/)
directory = str(path.parent)
- file_router = get_session_manager(client).file_router
+ workspace = get_session_manager(client).workspace
# Use relative paths (as the frontend would send when running from a
# subdirectory)
@@ -365,9 +365,9 @@ def test_copy_file_with_relative_paths(client: TestClient) -> None:
dest_relative = f"_copy_{path.name}"
copied_file = path.parent / dest_relative
- # Mock the directory property on the file router
+ # Mock the directory property on the workspace
with patch.object(
- type(file_router),
+ type(workspace),
"directory",
new_callable=lambda: property(lambda _: directory),
):
@@ -392,15 +392,15 @@ def test_copy_file_with_relative_paths(client: TestClient) -> None:
@with_session(SESSION_ID)
def test_path_traversal_save_blocked(client: TestClient) -> None:
- """Save endpoint must not write outside the router's directory."""
- filename = get_session_manager(client).file_router.get_unique_file_key()
+ """Save endpoint must not write outside the workspace's directory."""
+ filename = get_session_manager(client).workspace.get_unique_file_key()
assert filename
path = Path(filename)
directory = str(path.parent)
- file_router = get_session_manager(client).file_router
+ workspace = get_session_manager(client).workspace
with patch.object(
- type(file_router),
+ type(workspace),
"directory",
new_callable=lambda: property(lambda _: directory),
):
@@ -422,15 +422,15 @@ def test_path_traversal_save_blocked(client: TestClient) -> None:
@with_session(SESSION_ID)
def test_path_traversal_rename_blocked(client: TestClient) -> None:
- """Rename endpoint must not move files outside the router's directory."""
- filename = get_session_manager(client).file_router.get_unique_file_key()
+ """Rename endpoint must not move files outside the workspace's directory."""
+ filename = get_session_manager(client).workspace.get_unique_file_key()
assert filename
path = Path(filename)
directory = str(path.parent)
- file_router = get_session_manager(client).file_router
+ workspace = get_session_manager(client).workspace
with patch.object(
- type(file_router),
+ type(workspace),
"directory",
new_callable=lambda: property(lambda _: directory),
):
@@ -445,15 +445,15 @@ def test_path_traversal_rename_blocked(client: TestClient) -> None:
@with_session(SESSION_ID)
def test_path_traversal_copy_blocked(client: TestClient) -> None:
- """Copy endpoint must not write outside the router's directory."""
- filename = get_session_manager(client).file_router.get_unique_file_key()
+ """Copy endpoint must not write outside the workspace's directory."""
+ filename = get_session_manager(client).workspace.get_unique_file_key()
assert filename
path = Path(filename)
directory = str(path.parent)
- file_router = get_session_manager(client).file_router
+ workspace = get_session_manager(client).workspace
with patch.object(
- type(file_router),
+ type(workspace),
"directory",
new_callable=lambda: property(lambda _: directory),
):
@@ -475,7 +475,7 @@ def test_rename_propagates(
) -> None:
current_filename = get_session_manager(
client
- ).file_router.get_unique_file_key()
+ ).workspace.get_unique_file_key()
assert current_filename
assert os.path.exists(current_filename)
@@ -558,7 +558,7 @@ def test_read_code_without_saved_file(client: TestClient) -> None:
@with_session(SESSION_ID)
def test_save_with_unicode_content(client: TestClient) -> None:
"""Test save endpoint with unicode and special characters."""
- filename = get_session_manager(client).file_router.get_unique_file_key()
+ filename = get_session_manager(client).workspace.get_unique_file_key()
assert filename
path = Path(filename)
@@ -633,7 +633,7 @@ def test_rename_with_edge_case_filenames(client: TestClient) -> None:
for filename in EDGE_CASE_FILENAMES:
current_filename = get_session_manager(
client
- ).file_router.get_unique_file_key()
+ ).workspace.get_unique_file_key()
assert current_filename
new_path = Path(tmpdir) / filename
diff --git a/tests/_server/api/endpoints/test_home.py b/tests/_server/api/endpoints/test_home.py
index 01d97663a7..9533ebb99f 100644
--- a/tests/_server/api/endpoints/test_home.py
+++ b/tests/_server/api/endpoints/test_home.py
@@ -11,8 +11,11 @@ from typing import TYPE_CHECKING
import pytest
-from marimo._server.file_router import AppFileRouter
from marimo._server.models.home import MarimoFile
+from marimo._server.workspace import (
+ DirectoryWorkspace,
+ FixedFilesWorkspace,
+)
from marimo._session.model import SessionMode
from tests._server.mocks import get_session_manager, token_header, with_session
@@ -30,7 +33,7 @@ HEADERS = {
def test_workspace_files(client: TestClient) -> None:
current_filename = get_session_manager(
client
- ).file_router.get_unique_file_key()
+ ).workspace.get_unique_file_key()
assert current_filename
response = client.post(
@@ -64,7 +67,7 @@ def test_workspace_files_no_files(client: TestClient) -> None:
def test_running_notebooks(client: TestClient) -> None:
current_filename = get_session_manager(
client
- ).file_router.get_unique_file_key()
+ ).workspace.get_unique_file_key()
assert current_filename
response = client.post(
@@ -127,7 +130,9 @@ def test_workspace_files_in_run_mode(client: TestClient) -> None:
non_marimo_file = Path(temp_dir) / "text.txt"
non_marimo_file.write_text("This is not a marimo file")
- session_manager.file_router = AppFileRouter.from_directory(temp_dir)
+ session_manager.workspace = DirectoryWorkspace(
+ temp_dir, include_markdown=False
+ )
response = client.post(
"/api/home/workspace_files",
@@ -154,7 +159,9 @@ def test_workspace_files_run_mode_watch_directory_refreshes_add_remove(
file_one = Path(temp_dir) / "one.py"
file_one.write_text("import marimo\napp = marimo.App()")
- session_manager.file_router = AppFileRouter.from_directory(temp_dir)
+ session_manager.workspace = DirectoryWorkspace(
+ temp_dir, include_markdown=False
+ )
response_initial = client.post(
"/api/home/workspace_files",
@@ -203,7 +210,9 @@ def test_workspace_files_empty_directory(client: TestClient) -> None:
session_manager.mode = SessionMode.RUN
with tempfile.TemporaryDirectory() as temp_dir:
- session_manager.file_router = AppFileRouter.from_directory(temp_dir)
+ session_manager.workspace = DirectoryWorkspace(
+ temp_dir, include_markdown=False
+ )
response = client.post(
"/api/home/workspace_files",
@@ -239,10 +248,8 @@ def test_workspace_files_run_mode_allowlist(client: TestClient) -> None:
last_modified=file_two.stat().st_mtime,
),
]
- session_manager.file_router = AppFileRouter.from_files(
- marimo_files,
- directory=temp_dir,
- allow_single_file_key=False,
+ session_manager.workspace = FixedFilesWorkspace(
+ marimo_files, directory=temp_dir
)
response = client.post(
@@ -285,10 +292,8 @@ def test_workspace_files_run_mode_allowlist_skips_deleted_file(
last_modified=file_two.stat().st_mtime,
),
]
- session_manager.file_router = AppFileRouter.from_files(
- marimo_files,
- directory=temp_dir,
- allow_single_file_key=False,
+ session_manager.workspace = FixedFilesWorkspace(
+ marimo_files, directory=temp_dir
)
file_two.unlink()
@@ -330,7 +335,9 @@ def test_thumbnail_redirects_for_https_opengraph_image(
).lstrip()
)
- session_manager.file_router = AppFileRouter.from_directory(temp_dir)
+ session_manager.workspace = DirectoryWorkspace(
+ temp_dir, include_markdown=False
+ )
response = client.get(
"/og/thumbnail?file=notebook.py",
@@ -349,11 +356,9 @@ def test_tutorial_file_accessible_after_open(client: TestClient) -> None:
This is an integration test for issue #7424.
When a tutorial is opened via the endpoint, it creates a file in a temp
- directory. This test verifies that the file router can access that
+ directory. This test verifies that the workspace can access that
file despite it being outside the base directory.
"""
- from marimo._server.file_router import LazyListOfFilesAppFileRouter
-
# Open a tutorial
response = client.post(
"/api/home/tutorial/open",
@@ -364,13 +369,13 @@ def test_tutorial_file_accessible_after_open(client: TestClient) -> None:
data = response.json()
tutorial_path = data["path"]
- # Verify the temp directory was registered with the file router
+ # Verify the temp directory was registered with the workspace
session_manager = get_session_manager(client)
- file_router = session_manager.file_router
+ workspace = session_manager.workspace
- # Only test for directory-based routers
- if isinstance(file_router, LazyListOfFilesAppFileRouter):
- assert file_router.is_file_in_allowed_temp_dir(tutorial_path)
+ # Only test for directory-based workspaces
+ if isinstance(workspace, DirectoryWorkspace):
+ assert workspace.is_in_allowed_temp_dir(tutorial_path)
# Try to get a file manager for the tutorial file
# This should not raise an HTTPException about being outside the directory
@@ -381,13 +386,11 @@ def test_tutorial_file_accessible_after_open(client: TestClient) -> None:
@with_session(SESSION_ID)
def test_running_notebooks_returns_relative_paths(client: TestClient) -> None:
- """Test that running_notebooks returns paths relative to file router directory.
+ """Test that running_notebooks returns paths relative to workspace directory.
This is a regression test for the bug where `marimo edit subdirectory`
would return paths like `subdirectory/notebook.py` instead of `notebook.py`.
"""
- from marimo._server.file_router import LazyListOfFilesAppFileRouter
-
session_manager = get_session_manager(client)
# Create a temp directory structure: /tmp/xxx/subdir/notebook.py
@@ -413,15 +416,13 @@ def test_running_notebooks_returns_relative_paths(client: TestClient) -> None:
with open(notebook_path, "w") as f:
f.write(content)
- # Create a file router pointing to the subdirectory
+ # Create a workspace pointing to the subdirectory
# This simulates `marimo edit subdir`
- file_router = LazyListOfFilesAppFileRouter(
- subdir, include_markdown=False
- )
+ workspace = DirectoryWorkspace(subdir, include_markdown=False)
- # Replace the session manager's file router
- original_file_router = session_manager.file_router
- session_manager.file_router = file_router
+ # Replace the session manager's workspace
+ original_workspace = session_manager.workspace
+ session_manager.workspace = workspace
# Update the session's filename to the absolute path of the notebook
session = session_manager.get_session(SESSION_ID)
@@ -444,16 +445,14 @@ def test_running_notebooks_returns_relative_paths(client: TestClient) -> None:
assert files[0]["name"] == "notebook.py"
finally:
# Restore original state
- session_manager.file_router = original_file_router
+ session_manager.workspace = original_workspace
session.app_file_manager.filename = original_filename
@pytest.mark.skipif(sys.platform == "win32", reason="Failing on Windows CI")
@with_session(SESSION_ID, auto_shutdown=False)
def test_shutdown_session_returns_relative_paths(client: TestClient) -> None:
- """Test that shutdown_session returns paths relative to file router directory."""
- from marimo._server.file_router import LazyListOfFilesAppFileRouter
-
+ """Test that shutdown_session returns paths relative to workspace directory."""
session_manager = get_session_manager(client)
# Create a second session to test shutdown returns correct paths
@@ -479,12 +478,10 @@ def test_shutdown_session_returns_relative_paths(client: TestClient) -> None:
with open(notebook_path, "w") as f:
f.write(content)
- file_router = LazyListOfFilesAppFileRouter(
- subdir, include_markdown=False
- )
+ workspace = DirectoryWorkspace(subdir, include_markdown=False)
- original_file_router = session_manager.file_router
- session_manager.file_router = file_router
+ original_workspace = session_manager.workspace
+ session_manager.workspace = workspace
session = session_manager.get_session(SESSION_ID)
assert session is not None
@@ -503,7 +500,7 @@ def test_shutdown_session_returns_relative_paths(client: TestClient) -> None:
# After shutdown, no sessions remain
assert response.json() == {"files": []}
finally:
- session_manager.file_router = original_file_router
+ session_manager.workspace = original_workspace
# Note: session is already shut down, so we don't restore filename
@@ -516,8 +513,6 @@ def test_running_notebooks_handles_files_outside_directory(
client: TestClient,
) -> None:
"""Test that files outside the directory still get pretty_path treatment."""
- from marimo._server.file_router import LazyListOfFilesAppFileRouter
-
session_manager = get_session_manager(client)
auth_token = session_manager.auth_token
headers = token_header(auth_token)
@@ -550,13 +545,13 @@ def test_running_notebooks_handles_files_outside_directory(
with open(notebook_path, "w") as f:
f.write(content)
- # Set up file router pointing to router_dir
- file_router = LazyListOfFilesAppFileRouter(
+ # Set up workspace pointing to router_dir
+ workspace = DirectoryWorkspace(
router_dir, include_markdown=False
)
- original_file_router = session_manager.file_router
- session_manager.file_router = file_router
+ original_workspace = session_manager.workspace
+ session_manager.workspace = workspace
session = session_manager.get_session(SESSION_ID)
assert session is not None
@@ -579,5 +574,5 @@ def test_running_notebooks_handles_files_outside_directory(
# Path should contain the filename (exact path depends on CWD)
assert "outside.py" in files[0]["path"]
finally:
- session_manager.file_router = original_file_router
+ session_manager.workspace = original_workspace
session.app_file_manager.filename = original_filename
diff --git a/tests/_server/api/endpoints/test_resume_session.py b/tests/_server/api/endpoints/test_resume_session.py
index 9be93471bd..9200553000 100644
--- a/tests/_server/api/endpoints/test_resume_session.py
+++ b/tests/_server/api/endpoints/test_resume_session.py
@@ -114,7 +114,7 @@ def test_refresh_session(client: TestClient) -> None:
def test_save_session(client: TestClient) -> None:
filename = (
get_session_manager(client)
- .file_router.get_single_app_file_manager()
+ .workspace.get_single_app_file_manager()
.filename
)
with client.websocket_connect(_create_ws_url("123")) as websocket:
@@ -263,7 +263,7 @@ def test_resume_session_after_file_change(client: TestClient) -> None:
# Write to the notebook file to add a new cell
# we write it as the second to last cell
- filename = session_manager.file_router.get_unique_file_key()
+ filename = session_manager.workspace.get_unique_file_key()
assert filename
with open(filename) as f:
content = f.read()
diff --git a/tests/_server/api/endpoints/test_ws.py b/tests/_server/api/endpoints/test_ws.py
index 54cbddb4d7..245ce376a9 100644
--- a/tests/_server/api/endpoints/test_ws.py
+++ b/tests/_server/api/endpoints/test_ws.py
@@ -163,7 +163,7 @@ async def test_file_watcher_calls_reload(client: TestClient) -> None:
with client.websocket_connect(WS_URL) as websocket:
data = websocket.receive_json()
assert_kernel_ready_response(data)
- filename = session_manager.file_router.get_unique_file_key()
+ filename = session_manager.workspace.get_unique_file_key()
assert filename
with open(filename, "a") as f: # noqa: ASYNC230
f.write("\n# test")
@@ -710,7 +710,7 @@ async def test_edit_mode_without_session_ttl_no_delayed_cleanup(
def test_missing_file_key_closes_connection(client: TestClient) -> None:
"""Test that missing file key causes connection to close.
- This can happen when file_router.get_unique_file_key() returns None.
+ This can happen when workspace.get_unique_file_key() returns None.
"""
from unittest.mock import patch
@@ -718,7 +718,7 @@ def test_missing_file_key_closes_connection(client: TestClient) -> None:
# Mock get_unique_file_key to return None
with patch.object(
- session_manager.file_router,
+ session_manager.workspace,
"get_unique_file_key",
return_value=None,
):
diff --git a/tests/_server/api/endpoints/test_ws_rtc.py b/tests/_server/api/endpoints/test_ws_rtc.py
index 6059a36415..4d4cc72025 100644
--- a/tests/_server/api/endpoints/test_ws_rtc.py
+++ b/tests/_server/api/endpoints/test_ws_rtc.py
@@ -105,7 +105,7 @@ async def test_loro_cleanup_on_session_close(
doc = LoroDoc()
initial_code = doc.export(ExportMode.Snapshot())
- file_key = get_session_manager(client).file_router.get_unique_file_key()
+ file_key = get_session_manager(client).workspace.get_unique_file_key()
assert file_key is not None
with (
@@ -199,7 +199,7 @@ async def test_rtc_degrades_without_loro(client: TestClient) -> None:
"""
from unittest.mock import patch
- file_key = get_session_manager(client).file_router.get_unique_file_key()
+ file_key = get_session_manager(client).workspace.get_unique_file_key()
assert file_key is not None
# Clear any existing docs
@@ -237,7 +237,7 @@ async def test_rtc_degrades_without_loro(client: TestClient) -> None:
)
async def test_ws_sync_without_existing_session(client: TestClient) -> None:
"""Test that ws_sync endpoint requires an existing session."""
- file_key = get_session_manager(client).file_router.get_unique_file_key()
+ file_key = get_session_manager(client).workspace.get_unique_file_key()
assert file_key is not None
ws_sync_url = f"/ws_sync?file={file_key}&access_token=fake-token"
@@ -258,7 +258,7 @@ async def test_ws_sync_without_existing_session(client: TestClient) -> None:
)
async def test_ws_sync_cleanup_on_main_disconnect(client: TestClient) -> None:
"""Test that ws_sync clients are cleaned up when main session disconnects."""
- file_key = get_session_manager(client).file_router.get_unique_file_key()
+ file_key = get_session_manager(client).workspace.get_unique_file_key()
assert file_key is not None
# Clear any existing docs
diff --git a/tests/_server/mocks.py b/tests/_server/mocks.py
index 85f923c99e..0c395e2bfe 100644
--- a/tests/_server/mocks.py
+++ b/tests/_server/mocks.py
@@ -12,10 +12,13 @@ from marimo._config.manager import (
get_default_config_manager,
)
from marimo._server.config import StarletteServerStateInit
-from marimo._server.file_router import AppFileRouter
from marimo._server.lsp import NoopLspServer
from marimo._server.session_manager import SessionManager
from marimo._server.tokens import AuthToken, SkewProtectionToken
+from marimo._server.workspace import (
+ NotebookWorkspace,
+ SingleFileWorkspace,
+)
from marimo._session.model import SessionMode
from marimo._utils.marimo_path import MarimoPath
@@ -79,7 +82,7 @@ if __name__ == "__main__":
lsp_server = NoopLspServer()
sm = SessionManager(
- file_router=AppFileRouter.from_filename(MarimoPath(temp_file.name)),
+ workspace=SingleFileWorkspace.from_path(MarimoPath(temp_file.name)),
mode=mode,
quiet=False,
include_code=True,
@@ -96,28 +99,28 @@ if __name__ == "__main__":
@contextlib.contextmanager
-def file_router_scope(
- client: TestClient, file_router: AppFileRouter
+def workspace_scope(
+ client: TestClient, workspace: NotebookWorkspace
) -> Iterator[None]:
session_manager: SessionManager = cast(
Any, client.app
).state.session_manager
- original_file_router = session_manager.file_router
- session_manager.file_router = file_router
+ original_workspace = session_manager.workspace
+ session_manager.workspace = workspace
try:
yield
finally:
- session_manager.file_router = original_file_router
+ session_manager.workspace = original_workspace
-def with_file_router(
- file_router: AppFileRouter,
+def with_workspace(
+ workspace: NotebookWorkspace,
) -> Callable[[Callable[..., None]], Callable[..., None]]:
- """Decorator to create a session and close it after the test"""
+ """Decorator to swap a workspace for the duration of the test."""
def decorator(func: Callable[..., None]) -> Callable[..., None]:
def wrapper(client: TestClient, *args: Any, **kwargs: Any) -> None:
- with file_router_scope(client, file_router):
+ with workspace_scope(client, workspace):
func(client, *args, **kwargs)
return wrapper
diff --git a/tests/_server/rtc/test_rtc_doc.py b/tests/_server/rtc/test_rtc_doc.py
index 07be31cdf6..f0920a881b 100644
--- a/tests/_server/rtc/test_rtc_doc.py
+++ b/tests/_server/rtc/test_rtc_doc.py
@@ -6,8 +6,8 @@ from typing import TYPE_CHECKING, cast
import pytest
-from marimo._server.file_router import MarimoFileKey
from marimo._server.rtc.doc import LoroDocManager
+from marimo._server.workspace import MarimoFileKey
from marimo._types.ids import CellId_t
if sys.version_info >= (3, 11) and sys.version_info < (3, 14):
diff --git a/tests/_server/test_file_manager_absolute_path.py b/tests/_server/test_file_manager_absolute_path.py
index cb8b8de53e..141bc7d7ac 100644
--- a/tests/_server/test_file_manager_absolute_path.py
+++ b/tests/_server/test_file_manager_absolute_path.py
@@ -9,7 +9,7 @@ from pathlib import Path
import pytest
-from marimo._server.file_router import AppFileRouter
+from marimo._server.workspace import DirectoryWorkspace
from marimo._utils.http import HTTPException, HTTPStatus
is_windows = sys.platform == "win32"
@@ -44,7 +44,7 @@ if __name__ == "__main__":
# Test with absolute path
absolute_dir = str(test_dir.absolute())
- router = AppFileRouter.from_directory(absolute_dir)
+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)
# The directory should be stored correctly (always absolute)
assert router.directory == absolute_dir
@@ -58,7 +58,7 @@ if __name__ == "__main__":
assert file_info.path == "notebook.py"
# Try to get a file manager using the relative path from files list
- file_manager = router.get_file_manager(file_info.path)
+ file_manager = router.load(file_info.path)
assert file_manager is not None
# File manager resolves to absolute path
assert file_manager.filename == str(test_file)
@@ -95,7 +95,7 @@ if __name__ == "__main__":
# Test with relative path
relative_dir = "test_dir"
- router = AppFileRouter.from_directory(relative_dir)
+ router = DirectoryWorkspace(relative_dir, include_markdown=False)
# The directory is converted to absolute for consistency
assert router.directory == str(test_dir.absolute())
@@ -108,7 +108,7 @@ if __name__ == "__main__":
assert file_info.path == "notebook.py"
# Try to get a file manager using the relative file path
- file_manager = router.get_file_manager(file_info.path)
+ file_manager = router.load(file_info.path)
assert file_manager is not None
assert file_manager.is_notebook_named
# File manager resolves to absolute path
@@ -143,15 +143,15 @@ if __name__ == "__main__":
# Test with absolute path
absolute_dir = str(test_dir.absolute())
- absolute_router = AppFileRouter.from_directory(absolute_dir)
+ absolute_router = DirectoryWorkspace(
+ absolute_dir, include_markdown=False
+ )
absolute_files = absolute_router.files
assert len(absolute_files) > 0
# Get file manager with absolute path
absolute_file_path = absolute_files[0].path
- absolute_file_manager = absolute_router.get_file_manager(
- absolute_file_path
- )
+ absolute_file_manager = absolute_router.load(absolute_file_path)
# Change to the parent directory
original_cwd = os.getcwd()
@@ -160,15 +160,15 @@ if __name__ == "__main__":
# Test with relative path
relative_dir = "test_dir"
- relative_router = AppFileRouter.from_directory(relative_dir)
+ relative_router = DirectoryWorkspace(
+ relative_dir, include_markdown=False
+ )
relative_files = relative_router.files
assert len(relative_files) > 0
# Get file manager with relative path
relative_file_path = relative_files[0].path
- relative_file_manager = relative_router.get_file_manager(
- relative_file_path
- )
+ relative_file_manager = relative_router.load(relative_file_path)
# Both should reference the same file
assert (
@@ -215,7 +215,7 @@ if __name__ == "__main__":
# Set up router with absolute directory
absolute_dir = str(test_dir.absolute())
- router = AppFileRouter.from_directory(absolute_dir)
+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)
# Simulate the case where the client sends a relative filename
# This might happen if the frontend sends just the filename
@@ -229,7 +229,7 @@ if __name__ == "__main__":
assert os.path.exists(full_path)
# Try to get a file manager
- file_manager = router.get_file_manager(full_path)
+ file_manager = router.load(full_path)
assert file_manager is not None
assert file_manager.is_notebook_named
assert file_manager.read_file() is not None
@@ -266,7 +266,7 @@ if __name__ == "__main__":
# Set up router with absolute directory
absolute_dir = str(test_dir.absolute())
- router = AppFileRouter.from_directory(absolute_dir)
+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)
# Get the files before changing directory
files_before = router.files
@@ -285,7 +285,7 @@ if __name__ == "__main__":
# Try to get a file manager
file_path = files_after[0].path
- file_manager = router.get_file_manager(file_path)
+ file_manager = router.load(file_path)
assert file_manager is not None
assert file_manager.is_notebook_named
content = file_manager.read_file()
@@ -324,7 +324,7 @@ if __name__ == "__main__":
# Set up router with absolute directory
absolute_dir = str(test_dir.absolute())
- router = AppFileRouter.from_directory(absolute_dir)
+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)
# Change to a different directory
original_cwd = os.getcwd()
@@ -336,7 +336,7 @@ if __name__ == "__main__":
# the router's directory
relative_filename = "notebook.py"
- file_manager = router.get_file_manager(relative_filename)
+ file_manager = router.load(relative_filename)
assert file_manager is not None
assert file_manager.is_notebook_named
# Verify it opened the correct file
@@ -385,7 +385,7 @@ if __name__ == "__main__":
# Simulate: marimo edit /absolute/path/to/dir
absolute_dir = str(test_dir.absolute())
- router = AppFileRouter.from_directory(absolute_dir)
+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)
# Change to a different directory to simulate the server running elsewhere
original_cwd = os.getcwd()
@@ -400,7 +400,7 @@ if __name__ == "__main__":
file_info = files[0]
# This should work - using the full absolute path
- file_manager = router.get_file_manager(file_info.path)
+ file_manager = router.load(file_info.path)
assert file_manager is not None
assert file_manager.is_notebook_named
@@ -411,7 +411,7 @@ if __name__ == "__main__":
# This currently fails but should succeed
# The router should resolve the basename relative to its directory
try:
- file_manager_from_basename = router.get_file_manager(basename)
+ file_manager_from_basename = router.load(basename)
assert file_manager_from_basename is not None
assert file_manager_from_basename.is_notebook_named
except HTTPException:
@@ -457,7 +457,7 @@ if __name__ == "__main__":
# Simulate: marimo edit /absolute/path/to/dir
absolute_dir = str(test_dir.absolute())
- router = AppFileRouter.from_directory(absolute_dir)
+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)
# Change to a different directory
original_cwd = os.getcwd()
@@ -470,7 +470,7 @@ if __name__ == "__main__":
relative_path = os.path.join("subdir", "notebook.py")
try:
- file_manager = router.get_file_manager(relative_path)
+ file_manager = router.load(relative_path)
assert file_manager is not None
assert file_manager.is_notebook_named
except HTTPException:
@@ -497,7 +497,7 @@ if __name__ == "__main__":
# Test with absolute directory
absolute_dir = str(test_dir.absolute())
- router = AppFileRouter.from_directory(absolute_dir)
+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)
files = router.files
assert len(files) == 2
@@ -512,7 +512,7 @@ if __name__ == "__main__":
# Verify each file can be opened using its relative path
for file_info in files:
- file_manager = router.get_file_manager(file_info.path)
+ file_manager = router.load(file_info.path)
assert file_manager is not None
assert file_manager.is_notebook_named
@@ -536,15 +536,15 @@ if __name__ == "__main__":
# Create router for test_dir
absolute_dir = str(test_dir.absolute())
- router = AppFileRouter.from_directory(absolute_dir)
+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)
# Should be able to open file within the directory
- file_manager = router.get_file_manager(str(test_file.absolute()))
+ file_manager = router.load(str(test_file.absolute()))
assert file_manager is not None
# Should NOT be able to open file outside the directory
with pytest.raises(HTTPException) as exc_info:
- router.get_file_manager(str(other_file.absolute()))
+ router.load(str(other_file.absolute()))
assert exc_info.value.status_code == HTTPStatus.FORBIDDEN
assert "Access denied" in exc_info.value.detail
@@ -566,11 +566,11 @@ if __name__ == "__main__":
# Create router for test_dir
absolute_dir = str(test_dir.absolute())
- router = AppFileRouter.from_directory(absolute_dir)
+ router = DirectoryWorkspace(absolute_dir, include_markdown=False)
# Try to access the secret file using absolute path
with pytest.raises(HTTPException) as exc_info:
- router.get_file_manager(str(secret_file.absolute()))
+ router.load(str(secret_file.absolute()))
assert exc_info.value.status_code == HTTPStatus.FORBIDDEN
@@ -596,7 +596,9 @@ class TestRelativePathsInFileListing:
nested_file.write_text("import marimo\napp = marimo.App()")
# Create router
- router = AppFileRouter.from_directory(str(test_dir.absolute()))
+ router = DirectoryWorkspace(
+ str(test_dir.absolute()), include_markdown=False
+ )
files = router.files
file_paths = _collect_file_paths(files)
@@ -607,7 +609,7 @@ class TestRelativePathsInFileListing:
# Both should be openable using their relative paths
for path in _collect_file_paths(files):
- file_manager = router.get_file_manager(path)
+ file_manager = router.load(path)
assert file_manager is not None
assert file_manager.is_notebook_named
@@ -627,7 +629,9 @@ class TestRelativePathsInFileListing:
deep_file.write_text("import marimo\napp = marimo.App()")
# Create router
- router = AppFileRouter.from_directory(str(test_dir.absolute()))
+ router = DirectoryWorkspace(
+ str(test_dir.absolute()), include_markdown=False
+ )
files = router.files
file_paths = _collect_file_paths(files)
@@ -638,7 +642,7 @@ class TestRelativePathsInFileListing:
# Should be openable using the actual path from the files list
actual_paths = _collect_file_paths(files)
- file_manager = router.get_file_manager(actual_paths[0])
+ file_manager = router.load(actual_paths[0])
assert file_manager is not None
assert file_manager.filename == str(deep_file.absolute())
@@ -652,7 +656,9 @@ class TestRelativePathsInFileListing:
test_file = test_dir / "notebook.py"
test_file.write_text("import marimo\napp = marimo.App()")
- router = AppFileRouter.from_directory(str(test_dir.absolute()))
+ router = DirectoryWorkspace(
+ str(test_dir.absolute()), include_markdown=False
+ )
# Get the relative path from files list
files = router.files
@@ -661,12 +667,12 @@ class TestRelativePathsInFileListing:
assert relative_path == "notebook.py"
# Open with relative path
- manager_from_relative = router.get_file_manager(relative_path)
+ manager_from_relative = router.load(relative_path)
assert manager_from_relative is not None
# Open with absolute path
absolute_path = str(test_file.absolute())
- manager_from_absolute = router.get_file_manager(absolute_path)
+ manager_from_absolute = router.load(absolute_path)
assert manager_from_absolute is not None
# Both should point to the same file
@@ -683,11 +689,13 @@ class TestRelativePathsInFileListing:
outside_file = tmp_path / "outside.py"
outside_file.write_text("import marimo\napp = marimo.App()")
- router = AppFileRouter.from_directory(str(test_dir.absolute()))
+ router = DirectoryWorkspace(
+ str(test_dir.absolute()), include_markdown=False
+ )
# Try to access file outside using path traversal
with pytest.raises(HTTPException) as exc_info:
- router.get_file_manager("../outside.py")
+ router.load("../outside.py")
assert exc_info.value.status_code == HTTPStatus.FORBIDDEN
@@ -699,7 +707,9 @@ class TestRelativePathsInFileListing:
test_dir = tmp_path / "test_dir"
test_dir.mkdir()
- router = AppFileRouter.from_directory(str(test_dir.absolute()))
+ router = DirectoryWorkspace(
+ str(test_dir.absolute()), include_markdown=False
+ )
# Try various path traversal attempts
traversal_attempts = [
@@ -710,7 +720,7 @@ class TestRelativePathsInFileListing:
for attempt in traversal_attempts:
with pytest.raises(HTTPException) as exc_info:
- router.get_file_manager(str(attempt))
+ router.load(str(attempt))
assert exc_info.value.status_code == HTTPStatus.FORBIDDEN, (
f"Path traversal '{attempt}' should be blocked"
)
@@ -728,10 +738,12 @@ class TestFileManagerPathResolution:
test_file = test_dir / "notebook.py"
test_file.write_text("import marimo\napp = marimo.App()")
- router = AppFileRouter.from_directory(str(test_dir.absolute()))
+ router = DirectoryWorkspace(
+ str(test_dir.absolute()), include_markdown=False
+ )
# Try to open with ./ prefix
- file_manager = router.get_file_manager("./notebook.py")
+ file_manager = router.load("./notebook.py")
assert file_manager is not None
assert file_manager.filename == str(test_file.absolute())
@@ -746,10 +758,12 @@ class TestFileManagerPathResolution:
test_file = subdir / "notebook.py"
test_file.write_text("import marimo\napp = marimo.App()")
- router = AppFileRouter.from_directory(str(test_dir.absolute()))
+ router = DirectoryWorkspace(
+ str(test_dir.absolute()), include_markdown=False
+ )
# Path normalization should handle redundant slashes
- file_manager = router.get_file_manager("subdir//notebook.py")
+ file_manager = router.load("subdir//notebook.py")
assert file_manager is not None
assert file_manager.filename == str(test_file.absolute())
@@ -758,10 +772,12 @@ class TestFileManagerPathResolution:
test_dir = tmp_path / "test_dir"
test_dir.mkdir()
- router = AppFileRouter.from_directory(str(test_dir.absolute()))
+ router = DirectoryWorkspace(
+ str(test_dir.absolute()), include_markdown=False
+ )
with pytest.raises(HTTPException) as exc_info:
- router.get_file_manager("nonexistent.py")
+ router.load("nonexistent.py")
assert exc_info.value.status_code == HTTPStatus.NOT_FOUND
@@ -775,7 +791,7 @@ class TestFileManagerPathResolution:
os.chdir(tmp_path)
# Create router with relative path
- router = AppFileRouter.from_directory("test_dir")
+ router = DirectoryWorkspace("test_dir", include_markdown=False)
# Directory should be stored as absolute
assert router.directory is not None
@@ -798,7 +814,9 @@ class TestFileManagerPathResolution:
try:
# Create router while in tmp_path
os.chdir(tmp_path)
- router = AppFileRouter.from_directory(str(test_dir.absolute()))
+ router = DirectoryWorkspace(
+ str(test_dir.absolute()), include_markdown=False
+ )
# Get files list
files = router.files
@@ -809,7 +827,7 @@ class TestFileManagerPathResolution:
os.chdir(other_dir)
# Should still be able to open file using relative path
- file_manager = router.get_file_manager(relative_path)
+ file_manager = router.load(relative_path)
assert file_manager is not None
assert file_manager.filename == str(test_file.absolute())
diff --git a/tests/_server/test_session_manager.py b/tests/_server/test_session_manager.py
index 1d67633410..ce7f34b0ff 100644
--- a/tests/_server/test_session_manager.py
+++ b/tests/_server/test_session_manager.py
@@ -8,11 +8,11 @@ from unittest.mock import MagicMock, Mock
import pytest
from marimo._config.manager import get_default_config_manager
-from marimo._server.file_router import AppFileRouter
from marimo._server.lsp import LspServer
from marimo._server.session.listeners import RecentsTrackerListener
from marimo._server.session_manager import SessionManager
from marimo._server.tokens import AuthToken, SkewProtectionToken
+from marimo._server.workspace import NEW_FILE, EmptyWorkspace, infer_workspace
from marimo._session import (
KernelManager,
Session,
@@ -64,7 +64,7 @@ def mock_session():
@pytest.fixture
def session_manager():
return SessionManager(
- file_router=AppFileRouter.new_file(),
+ workspace=EmptyWorkspace(),
mode=SessionMode.EDIT,
quiet=False,
include_code=True,
@@ -100,7 +100,7 @@ async def test_create_session_new(
session_id,
mock_session_consumer,
query_params={},
- file_key=AppFileRouter.NEW_FILE,
+ file_key=NEW_FILE,
auto_instantiate=False,
)
assert session_id in session_manager.sessions
@@ -137,7 +137,7 @@ def test_maybe_resume_session_for_new_file(
# Resume the same session_id with a new file -> doesn't match
resumed_session = session_manager.maybe_resume_session(
- session_id, AppFileRouter.NEW_FILE
+ session_id, NEW_FILE
)
assert resumed_session is None
@@ -150,7 +150,7 @@ def test_maybe_resume_session_for_new_file(
# Resume with a different session_id -> doesn't match
resumed_session = session_manager.maybe_resume_session(
- "different_session_id", AppFileRouter.NEW_FILE
+ "different_session_id", NEW_FILE
)
assert resumed_session is None
@@ -199,9 +199,7 @@ def test_any_clients_connected_new_file(
) -> None:
add_session(session_manager, session_id, mock_session)
mock_session.app_file_manager = AppFileManager(filename=None)
- assert (
- session_manager.any_clients_connected(AppFileRouter.NEW_FILE) is False
- )
+ assert session_manager.any_clients_connected(NEW_FILE) is False
assert session_manager.any_clients_connected("different_file.py") is False
@@ -212,9 +210,7 @@ def test_any_clients_connected_existing_file(
) -> None:
add_session(session_manager, session_id, mock_session)
mock_session.app_file_manager = AppFileManager(filename=temp_marimo_file)
- assert (
- session_manager.any_clients_connected(AppFileRouter.NEW_FILE) is False
- )
+ assert session_manager.any_clients_connected(NEW_FILE) is False
assert session_manager.any_clients_connected(temp_marimo_file) is True
assert session_manager.any_clients_connected("different_file.py") is False
@@ -288,7 +284,7 @@ def test_session_manager_auth_token_edit_mode_with_provided_token():
"""Test that provided auth token is used in EDIT mode"""
provided_token = AuthToken("custom-edit-token")
session_manager = SessionManager(
- file_router=AppFileRouter.new_file(),
+ workspace=EmptyWorkspace(),
mode=SessionMode.EDIT,
quiet=False,
include_code=True,
@@ -309,7 +305,7 @@ def test_session_manager_auth_token_edit_mode_with_provided_token():
def test_session_manager_auth_token_edit_mode_without_provided_token():
"""Test that random auth token is generated in EDIT mode when none provided"""
session_manager = SessionManager(
- file_router=AppFileRouter.new_file(),
+ workspace=EmptyWorkspace(),
mode=SessionMode.EDIT,
quiet=False,
include_code=True,
@@ -334,7 +330,7 @@ def test_session_manager_auth_token_run_mode_with_provided_token():
"""Test that provided auth token is used in RUN mode"""
provided_token = AuthToken("custom-run-token")
session_manager = SessionManager(
- file_router=AppFileRouter.new_file(),
+ workspace=EmptyWorkspace(),
mode=SessionMode.RUN,
quiet=False,
include_code=True,
@@ -376,7 +372,7 @@ def test_session_manager_auth_token_run_mode_without_provided_token(
file_path.write_text(notebook_content)
session_manager = SessionManager(
- file_router=AppFileRouter.infer(str(file_path)),
+ workspace=infer_workspace(str(file_path)),
mode=SessionMode.RUN,
quiet=False,
include_code=True,
@@ -396,7 +392,7 @@ def test_session_manager_auth_token_run_mode_without_provided_token(
# Create another session manager with the same code - should have same token
session_manager2 = SessionManager(
- file_router=AppFileRouter.infer(str(file_path)),
+ workspace=infer_workspace(str(file_path)),
mode=SessionMode.RUN,
quiet=False,
include_code=True,
diff --git a/tests/_server/test_sessions.py b/tests/_server/test_sessions.py
index 1d89057efe..8d0694ecda 100644
--- a/tests/_server/test_sessions.py
+++ b/tests/_server/test_sessions.py
@@ -35,9 +35,9 @@ from marimo._runtime.commands import (
SyncGraphCommand,
UpdateUIElementCommand,
)
-from marimo._server.file_router import AppFileRouter
from marimo._server.session_manager import SessionManager
from marimo._server.utils import initialize_asyncio
+from marimo._server.workspace import SingleFileWorkspace
from marimo._session import Session
from marimo._session.consumer import SessionConsumer
from marimo._session.events import SessionEventBus
@@ -457,9 +457,9 @@ def __():
try:
# Create a session manager with file watching enabled
- file_router = AppFileRouter.from_filename(MarimoPath(tmp_file))
+ workspace = SingleFileWorkspace.from_path(MarimoPath(tmp_file))
session_manager = SessionManager(
- file_router=file_router,
+ workspace=workspace,
mode=SessionMode.EDIT,
quiet=True,
include_code=True,
@@ -605,9 +605,9 @@ def test_watch_mode_does_not_override_config(tmp_path: Path) -> None:
config_reader = get_default_config_manager(current_path=None)
# Create a session manager with watch mode enabled
- file_router = AppFileRouter.from_filename(MarimoPath(str(tmp_file)))
+ workspace = SingleFileWorkspace.from_path(MarimoPath(str(tmp_file)))
session_manager = SessionManager(
- file_router=file_router,
+ workspace=workspace,
mode=SessionMode.EDIT,
quiet=True,
include_code=True,
@@ -622,7 +622,7 @@ def test_watch_mode_does_not_override_config(tmp_path: Path) -> None:
)
session_manager_no_watch = SessionManager(
- file_router=file_router,
+ workspace=workspace,
mode=SessionMode.EDIT,
quiet=True,
include_code=True,
@@ -678,9 +678,9 @@ async def test_watch_mode_with_watcher_on_save_autorun(tmp_path: Path) -> None:
)
# Create a session manager with file watching enabled
- file_router = AppFileRouter.from_filename(MarimoPath(str(tmp_file)))
+ workspace = SingleFileWorkspace.from_path(MarimoPath(str(tmp_file)))
session_manager = SessionManager(
- file_router=file_router,
+ workspace=workspace,
mode=SessionMode.EDIT,
quiet=True,
include_code=True,
@@ -787,9 +787,9 @@ async def test_watch_mode_with_watcher_on_save_lazy(tmp_path: Path) -> None:
)
# Create a session manager with file watching enabled
- file_router = AppFileRouter.from_filename(MarimoPath(str(tmp_file)))
+ workspace = SingleFileWorkspace.from_path(MarimoPath(str(tmp_file)))
session_manager = SessionManager(
- file_router=file_router,
+ workspace=workspace,
mode=SessionMode.EDIT,
quiet=True,
include_code=True,
@@ -878,9 +878,9 @@ def __():
try:
# Create a session manager with file watching enabled
- file_router = AppFileRouter.from_filename(MarimoPath(str(tmp_path1)))
+ workspace = SingleFileWorkspace.from_path(MarimoPath(str(tmp_path1)))
session_manager = SessionManager(
- file_router=file_router,
+ workspace=workspace,
mode=SessionMode.EDIT,
quiet=True,
include_code=True,
diff --git a/tests/_server/test_file_router.py b/tests/_server/test_workspace.py
similarity index 67%
rename from tests/_server/test_file_router.py
rename to tests/_server/test_workspace.py
index e163593595..c4b10629ea 100644
--- a/tests/_server/test_file_router.py
+++ b/tests/_server/test_workspace.py
@@ -8,19 +8,22 @@ from pathlib import Path
import pytest
-from marimo._server.file_router import (
- AppFileRouter,
- FileInfo,
- LazyListOfFilesAppFileRouter,
- ListOfFilesAppFileRouter,
- NewFileAppFileRouter,
- count_files,
- flatten_files,
-)
from marimo._server.files.directory_scanner import is_marimo_app
from marimo._server.files.path_validator import PathValidator
+from marimo._server.models.files import FileInfo
from marimo._server.models.home import MarimoFile
+from marimo._server.workspace import (
+ NEW_FILE,
+ DirectoryWorkspace,
+ EmptyWorkspace,
+ FixedFilesWorkspace,
+ SingleFileWorkspace,
+ count_files,
+ flatten_files,
+ infer_workspace,
+)
from marimo._utils.http import HTTPException, HTTPStatus
+from marimo._utils.marimo_path import MarimoPath
file_contents = """
import marimo
@@ -29,7 +32,16 @@ app = marimo.App()
"""
-class TestAppFileRouter(unittest.TestCase):
+def _marimo_file(path: str, name: str = "test.py") -> MarimoFile:
+ """Build a ``MarimoFile`` for a real path on disk."""
+ return MarimoFile(
+ name=name,
+ path=path,
+ last_modified=os.path.getmtime(path),
+ )
+
+
+class TestNotebookWorkspace(unittest.TestCase):
def setUp(self):
# Create a temporary directory
self.test_dir = tempfile.mkdtemp()
@@ -70,176 +82,286 @@ class TestAppFileRouter(unittest.TestCase):
shutil.rmtree(self.test_dir)
def test_infer_file(self):
- # Test infer method with a file path
- router = AppFileRouter.infer(self.test_file1.name)
- assert isinstance(router, ListOfFilesAppFileRouter)
+ workspace = infer_workspace(self.test_file1.name)
+ assert isinstance(workspace, SingleFileWorkspace)
def test_infer_directory(self):
- # Test infer method with a directory path
- router = AppFileRouter.infer(self.test_dir)
- assert isinstance(router, LazyListOfFilesAppFileRouter)
-
- def test_from_files(self):
- # Test creating a router from a list of files
- files = [
- MarimoFile(
- name="test.py",
- path=self.test_file1.name,
- last_modified=os.path.getmtime(self.test_file1.name),
- )
- ]
- router = AppFileRouter.from_files(files)
- assert isinstance(router, ListOfFilesAppFileRouter)
-
- def test_new_file_router(self):
- # Test the NewFileAppFileRouter
- router = AppFileRouter.new_file()
- assert isinstance(router, NewFileAppFileRouter)
- assert router.maybe_get_single_file() is None
-
- def test_lazy_list_of_files(self):
- # Test the lazy loading of files in a directory
- router = LazyListOfFilesAppFileRouter(
- self.test_dir, include_markdown=False
- )
- files = router.files
- assert (
- len(files) == 3
- ) # Assuming the directory only contains the two created files
+ workspace = infer_workspace(self.test_dir)
+ assert isinstance(workspace, DirectoryWorkspace)
+
+ def test_fixed_files_workspace(self):
+ workspace = FixedFilesWorkspace([_marimo_file(self.test_file1.name)])
+ assert workspace.single_file() is None
+
+ def test_empty_workspace(self):
+ workspace = EmptyWorkspace()
+ assert workspace.single_file() is None
+ assert workspace.get_unique_file_key() == NEW_FILE
- def test_lazy_list_with_broken_symlinks(self):
- # Test the lazy loading of files in a directory with broken symlinks
- # Create a broken symlink
+ def test_directory_workspace_lists_files(self):
+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=False)
+ files = workspace.files
+ assert len(files) == 3
+
+ def test_directory_workspace_with_broken_symlinks(self):
broken_symlink = os.path.join(self.test_dir, "broken_symlink.py")
os.symlink("non_existent_file", broken_symlink)
- router = LazyListOfFilesAppFileRouter(
- self.test_dir, include_markdown=False
- )
- files = router.files
+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=False)
+ files = workspace.files
assert len(files) == 3
-
- # Remove the broken symlink
os.unlink(broken_symlink)
- def test_lazy_list_with_markdown(self):
- # Test the lazy loading of files in a directory with markdown
- router = LazyListOfFilesAppFileRouter(
- self.test_dir, include_markdown=True
- )
- # Create markdown files
- files = router.files
- assert len(files) == 4
+ def test_directory_workspace_set_include_markdown_mutates_in_place(self):
+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=True)
+ assert len(workspace.files) == 4
- # Toggling markdown
- router = router.toggle_markdown(False)
- files = router.files
- assert len(files) == 3
+ workspace.set_include_markdown(False)
+ assert len(workspace.files) == 3
- # Toggle markdown back
- router = router.toggle_markdown(True)
- files = router.files
- assert len(files) == 4
-
- def test_list_of_files_restricts_access(self):
- files = [
- MarimoFile(
- name="test.py",
- path=self.test_file1.name,
- last_modified=os.path.getmtime(self.test_file1.name),
- )
- ]
- router = ListOfFilesAppFileRouter(files)
+ workspace.set_include_markdown(True)
+ assert len(workspace.files) == 4
+
+ def test_fixed_files_restricts_access(self):
+ workspace = FixedFilesWorkspace([_marimo_file(self.test_file1.name)])
with pytest.raises(HTTPException) as exc:
- router.get_file_manager(self.test_file2.name)
+ workspace.load(self.test_file2.name)
assert exc.value.status_code == HTTPStatus.NOT_FOUND
- def test_list_of_files_disallows_dynamic_allowlist(self):
- files = [
- MarimoFile(
- name="test.py",
- path=self.test_file1.name,
- last_modified=os.path.getmtime(self.test_file1.name),
- )
- ]
- router = ListOfFilesAppFileRouter(files, allow_dynamic=False)
- router.register_allowed_file(self.test_file2.name)
+ def test_fixed_files_register_allowed_path_is_noop(self):
+ workspace = FixedFilesWorkspace([_marimo_file(self.test_file1.name)])
+ workspace.register_allowed_path(self.test_file2.name)
with pytest.raises(HTTPException) as exc:
- router.get_file_manager(self.test_file2.name)
+ workspace.load(self.test_file2.name)
assert exc.value.status_code == HTTPStatus.NOT_FOUND
- def test_list_of_files_disallows_new_file_key(self):
- files = [
- MarimoFile(
- name="test.py",
- path=self.test_file1.name,
- last_modified=os.path.getmtime(self.test_file1.name),
- )
- ]
- router = ListOfFilesAppFileRouter(files, allow_single_file_key=False)
+ def test_single_file_register_allowed_path_grows_allowlist(self):
+ workspace = SingleFileWorkspace(_marimo_file(self.test_file1.name))
+ workspace.register_allowed_path(self.test_file2.name)
+ manager = workspace.load(self.test_file2.name)
+ assert manager is not None
+
+ def test_fixed_files_disallows_new_file_key(self):
+ workspace = FixedFilesWorkspace([_marimo_file(self.test_file1.name)])
with pytest.raises(HTTPException) as exc:
- router.get_file_manager(AppFileRouter.NEW_FILE)
+ workspace.load(NEW_FILE)
assert exc.value.status_code == HTTPStatus.NOT_FOUND
- def test_list_of_files_resolve_file_path_supports_relative_key(self):
- files = [
- MarimoFile(
- name="test.py",
- path=self.test_file1.name,
- last_modified=os.path.getmtime(self.test_file1.name),
- )
- ]
- router = ListOfFilesAppFileRouter(files, directory=self.test_dir)
+ def test_fixed_files_resolve_supports_relative_key(self):
+ workspace = FixedFilesWorkspace(
+ [_marimo_file(self.test_file1.name)],
+ directory=self.test_dir,
+ )
relative_key = str(
Path(self.test_file1.name).relative_to(self.test_dir)
)
- resolved = router.resolve_file_path(relative_key)
+ resolved = workspace.resolve(relative_key)
assert resolved == self.test_file1.name
- def test_lazy_list_of_get_app_file_manager(self):
- router = LazyListOfFilesAppFileRouter(
- self.test_dir, include_markdown=False
- )
+ def test_directory_workspace_load(self):
+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=False)
filename = self.test_file1.name
assert os.path.exists(filename), f"File {filename} does not exist"
- file_manager = router.get_file_manager(key=filename)
+ file_manager = workspace.load(key=filename)
assert file_manager.filename == filename
- def test_lazy_list_of_get_app_file_manager_nested(self):
- router = LazyListOfFilesAppFileRouter(
- self.test_dir, include_markdown=False
- )
+ def test_directory_workspace_load_nested(self):
+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=False)
nested_filename = self.nested_file.name
- file_manager = router.get_file_manager(key=nested_filename)
+ file_manager = workspace.load(key=nested_filename)
assert file_manager.filename == self.nested_file.name
assert file_manager.filename is not None
assert os.path.exists(file_manager.filename)
assert file_manager.filename.startswith(self.test_dir)
assert "nested" in file_manager.filename
- def test_list_of_files_resolves_dotdot_in_path(self):
+ def test_single_file_resolves_dotdot_in_path(self):
"""Paths with '..' components should resolve correctly.
Regression test for https://github.com/marimo-team/marimo/issues/8414
"""
- # Build a path with '..' that resolves to test_file1
- # e.g. /tmp/dir/nested/../file.py -> /tmp/dir/file.py
dotdot_path = os.path.join(
self.nested_dir, "..", os.path.basename(self.test_file1.name)
)
- files = [
- MarimoFile(
- name="test.py",
- path=dotdot_path,
- last_modified=os.path.getmtime(self.test_file1.name),
- )
- ]
- router = ListOfFilesAppFileRouter(files)
- key = router.get_unique_file_key()
+ workspace = SingleFileWorkspace.from_path(MarimoPath(dotdot_path))
+ key = workspace.get_unique_file_key()
assert key is not None
- resolved = router.resolve_file_path(key)
+ resolved = workspace.resolve(key)
+ assert resolved is not None
+ assert os.path.exists(resolved)
+
+ def test_no_op_capabilities_default_to_inert(self):
+ """All non-directory workspaces share inert defaults for capabilities."""
+ workspaces = [
+ EmptyWorkspace(),
+ SingleFileWorkspace.from_path(MarimoPath(self.test_file1.name)),
+ FixedFilesWorkspace([]),
+ ]
+ for workspace in workspaces:
+ # No-ops shouldn't raise.
+ workspace.register_temp_dir("/tmp/whatever")
+ workspace.invalidate()
+ workspace.set_include_markdown(True)
+ assert workspace.is_in_allowed_temp_dir("/anywhere") is False
+
+ # ----- security: SingleFileWorkspace -----
+
+ def test_single_file_blocks_unrelated_absolute_path(self):
+ """A SingleFileWorkspace must reject any path other than its file."""
+ workspace = SingleFileWorkspace.from_path(
+ MarimoPath(self.test_file1.name)
+ )
+ with pytest.raises(HTTPException) as exc:
+ workspace.resolve(self.test_file2.name)
+ assert exc.value.status_code == HTTPStatus.NOT_FOUND
+
+ def test_single_file_blocks_path_traversal(self):
+ """`..` segments that escape the allowed file are rejected."""
+ workspace = SingleFileWorkspace.from_path(
+ MarimoPath(self.test_file1.name)
+ )
+ # /tmp/dir/file1.py + /../../etc/passwd → /etc/passwd, not in allowlist
+ traversal = os.path.join(
+ self.nested_dir, "..", "..", "..", "etc", "passwd"
+ )
+ with pytest.raises(HTTPException) as exc:
+ workspace.resolve(traversal)
+ assert exc.value.status_code == HTTPStatus.NOT_FOUND
+
+ def test_single_file_accepts_dotdot_that_normalizes_to_allowed(self):
+ """`..` segments that normalize back to the allowed file are accepted."""
+ workspace = SingleFileWorkspace.from_path(
+ MarimoPath(self.test_file1.name)
+ )
+ # nested/../<basename of test_file1> resolves to test_file1
+ equivalent = os.path.join(
+ self.nested_dir, "..", os.path.basename(self.test_file1.name)
+ )
+ resolved = workspace.resolve(equivalent)
+ assert resolved == self.test_file1.name
+
+ # ----- security: FixedFilesWorkspace -----
+
+ def test_fixed_files_blocks_path_traversal(self):
+ """Relative `..` keys that escape the allowlist must 404."""
+ workspace = FixedFilesWorkspace(
+ [_marimo_file(self.test_file1.name)],
+ directory=self.test_dir,
+ )
+ with pytest.raises(HTTPException) as exc:
+ workspace.resolve("../../../etc/passwd")
+ assert exc.value.status_code == HTTPStatus.NOT_FOUND
+
+ def test_fixed_files_blocks_absolute_path_outside_allowlist(self):
+ """Absolute paths outside the allowlist must 404 even if they exist."""
+ workspace = FixedFilesWorkspace(
+ [_marimo_file(self.test_file1.name)],
+ directory=self.test_dir,
+ )
+ # test_file2 exists on disk inside the same directory but is not on the
+ # allowlist — must still be denied.
+ with pytest.raises(HTTPException) as exc:
+ workspace.resolve(self.test_file2.name)
+ assert exc.value.status_code == HTTPStatus.NOT_FOUND
+
+ def test_fixed_files_accepts_dotdot_that_normalizes_to_allowed(self):
+ """Regression test for #8414 — ``..`` paths must normalize correctly."""
+ dotdot_path = os.path.join(
+ self.nested_dir, "..", os.path.basename(self.test_file1.name)
+ )
+ workspace = FixedFilesWorkspace([_marimo_file(dotdot_path)])
+ resolved = workspace.resolve(dotdot_path)
assert resolved is not None
assert os.path.exists(resolved)
+ def test_fixed_files_new_file_key_is_rejected(self):
+ """``__new__`` keys are not valid in run mode."""
+ workspace = FixedFilesWorkspace([])
+ with pytest.raises(HTTPException) as exc:
+ workspace.resolve(NEW_FILE)
+ assert exc.value.status_code == HTTPStatus.NOT_FOUND
+
+ # ----- security: DirectoryWorkspace -----
+
+ def test_directory_workspace_new_file_prefix_does_not_leak(self):
+ """``__new__`` prefix returns None — does not bypass containment.
+
+ ``startswith(NEW_FILE)`` could otherwise be coaxed into accepting
+ crafted keys like ``__new__../etc/passwd``; verify those still resolve
+ to ``None`` (a blank notebook), never an arbitrary file.
+ """
+ workspace = DirectoryWorkspace(self.test_dir, include_markdown=False)
+ for key in (
+ NEW_FILE,
+ f"{NEW_FILE}../etc/passwd",
+ f"{NEW_FILE}/etc/passwd",
+ ):
+ assert workspace.resolve(key) is None
+
+ def test_directory_workspace_temp_dir_does_not_enable_traversal(self):
+ """A temp-dir bypass must not let attackers escape via ``..``."""
+ with (
+ tempfile.TemporaryDirectory() as base_dir,
+ tempfile.TemporaryDirectory() as temp_dir,
+ ):
+ workspace = DirectoryWorkspace(base_dir, include_markdown=False)
+ workspace.register_temp_dir(temp_dir)
+
+ # Path that traverses through the temp dir to escape entirely.
+ traversal = os.path.join(temp_dir, "..", "..", "etc", "passwd")
+ with pytest.raises(HTTPException) as exc:
+ workspace.resolve(traversal)
+ # The path normalizes to /etc/passwd (or equivalent), neither in
+ # the temp dir nor in the workspace directory — must be denied.
+ assert exc.value.status_code in (
+ HTTPStatus.FORBIDDEN,
+ HTTPStatus.NOT_FOUND,
+ )
+
+ # ----- security: EmptyWorkspace -----
+
+ def test_empty_workspace_load_with_new_file_key_returns_blank(self):
+ """Bare ``__new__`` key always yields an unbacked manager."""
+ workspace = EmptyWorkspace()
+ manager = workspace.load(NEW_FILE)
+ assert manager.filename is None
+
+ def test_empty_workspace_load_with_nonexistent_path_404s(self):
+ """Concrete keys that don't exist on disk must 404."""
+ workspace = EmptyWorkspace()
+ with pytest.raises(HTTPException) as exc:
+ workspace.load("/this/path/does/not/exist.py")
+ assert exc.value.status_code == HTTPStatus.NOT_FOUND
+
+ def test_empty_workspace_resolve_returns_absolute_normalized(self):
+ """``resolve`` must return an absolute, normalized path so downstream
+ lookups (session keys, comparisons) don't mismatch between relative
+ and absolute spellings of the same file.
+ """
+ original_cwd = os.getcwd()
+ try:
+ os.chdir(self.test_dir)
+ relative_key = os.path.basename(self.test_file1.name)
+ workspace = EmptyWorkspace()
+ resolved = workspace.resolve(relative_key)
+ assert resolved is not None
+ assert os.path.isabs(resolved)
+ assert os.path.samefile(resolved, self.test_file1.name)
+ finally:
+ os.chdir(original_cwd)
+
+ def test_empty_workspace_load_with_existing_path_falls_back(self):
+ """``marimo new`` boots an EmptyWorkspace; opening a recent file must
+ still work via the unconditional existence fallback.
+
+ This is intentionally permissive — there's no allowlist, since the
+ boot mode has no concept of one. Threat model: anyone able to hit
+ ``marimo new``'s endpoint already has the same trust level as the
+ process owner.
+ """
+ workspace = EmptyWorkspace()
+ manager = workspace.load(self.test_file1.name)
+ assert manager.filename == self.test_file1.name
+
def test_flatten_files() -> None:
root = FileInfo(
@@ -591,7 +713,7 @@ def test_error_path_returns_false_and_logs(tmp_path: Path):
def test_lazy_router_respects_max_files(tmp_path: Path):
- """Test that LazyListOfFilesAppFileRouter enforces MAX_FILES limit"""
+ """Test that DirectoryWorkspace enforces MAX_FILES limit"""
# Create a directory with more files than MAX_FILES
# To make this test fast, we'll use a monkey-patch approach
# by temporarily reducing MAX_FILES
@@ -607,9 +729,7 @@ def test_lazy_router_respects_max_files(tmp_path: Path):
f = tmp_path / f"app_{i}.py"
f.write_text("import marimo\napp = marimo.App()\n")
- router = LazyListOfFilesAppFileRouter(
- str(tmp_path), include_markdown=False
- )
+ router = DirectoryWorkspace(str(tmp_path), include_markdown=False)
files = router.files
# Should only get MAX_FILES worth of files
@@ -623,7 +743,7 @@ def test_lazy_router_respects_max_files(tmp_path: Path):
def test_lazy_router_skips_common_dirs(tmp_path: Path):
- """Test that LazyListOfFilesAppFileRouter skips common directories"""
+ """Test that DirectoryWorkspace skips common directories"""
# Create directories that should be skipped
skip_dirs = [
".venv",
@@ -645,9 +765,7 @@ def test_lazy_router_skips_common_dirs(tmp_path: Path):
root_file = tmp_path / "root_app.py"
root_file.write_text("import marimo\napp = marimo.App()\n")
- router = LazyListOfFilesAppFileRouter(
- str(tmp_path), include_markdown=False
- )
+ router = DirectoryWorkspace(str(tmp_path), include_markdown=False)
files = router.files
# Should only find the root file, not files in skipped directories
@@ -670,9 +788,7 @@ def test_lazy_router_counts_nested_files(tmp_path: Path):
nested_file = nested_dir / "nested.py"
nested_file.write_text("import marimo\napp = marimo.App()\n")
- router = LazyListOfFilesAppFileRouter(
- str(tmp_path), include_markdown=False
- )
+ router = DirectoryWorkspace(str(tmp_path), include_markdown=False)
files = router.files
total_files = count_files(files)
@@ -698,13 +814,11 @@ def test_lazy_router_allows_temp_dir_files(tmp_path: Path):
temp_file.write_text("import marimo\napp = marimo.App()\n")
# Create router for base directory
- router = LazyListOfFilesAppFileRouter(
- str(base_dir), include_markdown=False
- )
+ router = DirectoryWorkspace(str(base_dir), include_markdown=False)
# Without registering temp dir, accessing temp file should fail
with pytest.raises(HTTPException) as exc_info:
- router.get_file_manager(str(temp_file))
+ router.load(str(temp_file))
assert exc_info.value.status_code == HTTPStatus.FORBIDDEN
assert "outside the allowed directory" in exc_info.value.detail
@@ -712,7 +826,7 @@ def test_lazy_router_allows_temp_dir_files(tmp_path: Path):
router.register_temp_dir(str(temp_dir))
# Now accessing the temp file should succeed
- manager = router.get_file_manager(str(temp_file))
+ manager = router.load(str(temp_file))
assert manager is not None
assert manager.path == str(temp_file)
@@ -738,21 +852,19 @@ def test_lazy_router_temp_dir_doesnt_affect_normal_files(
other_temp_dir.mkdir()
# Create router
- router = LazyListOfFilesAppFileRouter(
- str(base_dir), include_markdown=False
- )
+ router = DirectoryWorkspace(str(base_dir), include_markdown=False)
# Register a different temp directory (not containing our outside_file)
router.register_temp_dir(str(other_temp_dir))
# Base file should still be accessible
- manager = router.get_file_manager(str(base_file))
+ manager = router.load(str(base_file))
assert manager is not None
assert manager.path == str(base_file)
# Outside file should still be blocked (not in registered temp dir)
with pytest.raises(HTTPException) as exc_info:
- router.get_file_manager(str(outside_file))
+ router.load(str(outside_file))
assert exc_info.value.status_code == HTTPStatus.FORBIDDEN
@@ -783,8 +895,6 @@ def test_lazy_router_symlink_directory_outside_allowed(tmp_path: Path):
# Symlinks are preserved (not resolved), so the path
# base_dir/shared/outside.py is inside base_dir
- router = LazyListOfFilesAppFileRouter(
- str(base_dir), include_markdown=False
- )
- manager = router.get_file_manager(str(file_through_symlink))
+ router = DirectoryWorkspace(str(base_dir), include_markdown=False)
+ manager = router.load(str(file_through_symlink))
assert manager is not None