dara-core 1.20.2__py3-none-any.whl → 1.21.0__py3-none-any.whl

dara/core/main.py

@@ -16,24 +16,31 @@ limitations under the License.
 """
 
 import asyncio
+import json
 import os
 import sys
+import traceback
+from collections.abc import Mapping
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import asynccontextmanager
 from importlib.util import find_spec
 from inspect import iscoroutine
 from pathlib import Path
-from typing import Optional
+from typing import Annotated, Any, Dict, List, Optional
+from urllib.parse import unquote
 
 from anyio import create_task_group
-from fastapi import FastAPI, HTTPException, Request
-from fastapi.encoders import ENCODERS_BY_TYPE
-from fastapi.responses import HTMLResponse
+from fastapi import Body, Depends, FastAPI, HTTPException, Request
+from fastapi import Path as PathParam
+from fastapi.encoders import ENCODERS_BY_TYPE, jsonable_encoder
 from fastapi.staticfiles import StaticFiles
 from prometheus_client import start_http_server
+from pydantic import BaseModel, Field
+from starlette.responses import FileResponse
 from starlette.templating import Jinja2Templates, _TemplateResponse
 
 from dara.core.auth import auth_router
+from dara.core.auth.routes import verify_session
 from dara.core.configuration import Configuration, ConfigurationBuilder
 from dara.core.defaults import (
     blank_template,
@@ -44,18 +51,21 @@ from dara.core.defaults import (
 from dara.core.internal.cache_store import CacheStore
 from dara.core.internal.cgroup import get_cpu_count, set_memory_limit
 from dara.core.internal.custom_response import CustomResponse
-from dara.core.internal.devtools import send_error_for_session
+from dara.core.internal.devtools import print_stacktrace, send_error_for_session
 from dara.core.internal.encoder_registry import encoder_registry
+from dara.core.internal.execute_action import CURRENT_ACTION_ID, execute_action_sync
+from dara.core.internal.normalization import NormalizedPayload, denormalize, normalize
 from dara.core.internal.pool import TaskPool
 from dara.core.internal.registries import (
     action_def_registry,
+    action_registry,
     auth_registry,
     component_registry,
     config_registry,
     custom_ws_handlers_registry,
     latest_value_registry,
     sessions_registry,
-    template_registry,
+    static_kwargs_registry,
     utils_registry,
     websocket_registry,
 )
@@ -64,7 +74,7 @@ from dara.core.internal.routing import create_router, error_decorator
 from dara.core.internal.settings import get_settings
 from dara.core.internal.tasks import TaskManager
 from dara.core.internal.utils import enforce_sso, import_config
-from dara.core.internal.websocket import WebsocketManager
+from dara.core.internal.websocket import WS_CHANNEL, WebsocketManager
 from dara.core.js_tooling.js_utils import (
     BuildCache,
     BuildMode,
@@ -72,6 +82,16 @@ from dara.core.js_tooling.js_utils import (
     rebuild_js,
 )
 from dara.core.logging import LoggingMiddleware, dev_logger, eng_logger, http_logger
+from dara.core.router import convert_template_to_router
+
+
+class CacheStaticFiles(StaticFiles):
+    async def get_response(self, path, scope):
+        response = await super().get_response(path, scope)
+        # add 1 year cache for static assets
+        if isinstance(response, FileResponse) and path.endswith('.css') or path.endswith('.umd.js'):
+            response.headers['Cache-Control'] = 'public, max-age=31536000'
+        return response
 
 
 def _start_application(config: Configuration):
@@ -94,18 +114,9 @@ def _start_application(config: Configuration):
     import fastapi_vite_dara
     import fastapi_vite_dara.config
 
-    if len(config.pages) > 0:
-        BASE_DIR = Path(__file__).parent
-        jinja_templates = Jinja2Templates(directory=str(Path(BASE_DIR, 'jinja')))
-        jinja_templates.env.globals['vite_hmr_client'] = fastapi_vite_dara.vite_hmr_client
-        jinja_templates.env.globals['vite_asset'] = fastapi_vite_dara.vite_asset
-        jinja_templates.env.globals['static_url'] = fastapi_vite_dara.config.settings.static_url
-        jinja_templates.env.globals['base_url'] = os.getenv('DARA_BASE_URL', '')
-        jinja_templates.env.globals['entry'] = '_entry.tsx'
-
-        # If --enable-hmr or --reload enabled, set live reload to true
-        if os.environ.get('DARA_HMR_MODE') == 'TRUE' or os.environ.get('DARA_LIVE_RELOAD') == 'TRUE':
-            config.live_reload = True
+    # If --enable-hmr or --reload enabled, set live reload to true
+    if os.environ.get('DARA_HMR_MODE') == 'TRUE' or os.environ.get('DARA_LIVE_RELOAD') == 'TRUE':
+        config.live_reload = True
 
     # Configure the default executor for threads run via the async loop
     loop = asyncio.get_event_loop()
@@ -259,26 +270,6 @@ def _start_application(config: Configuration):
     for key, value in encoder_registry.items():
         ENCODERS_BY_TYPE[key] = value['serialize']
 
-    # Generate a new build_cache
-    try:
-        build_cache = BuildCache.from_config(config)
-        build_diff = build_cache.get_diff()
-
-        # Only build if there's pages to build, otherwise assume Dara is only used for API
-        if len(config.pages) > 0:
-            dev_logger.debug(
-                'Building JS...',
-                extra={
-                    'New build cache': build_cache.model_dump(),
-                    'Difference from last cache': build_diff.model_dump(),
-                },
-            )
-            rebuild_js(build_cache, build_diff)
-
-    except Exception as e:
-        dev_logger.error('Error building JS', error=e)
-        sys.exit(1)
-
     # Loop over registered components and add to the registry
     eng_logger.info(f'Registering components [{", ".join([c.name for c in config.components])}]')
     for component in config.components:
@@ -292,37 +283,64 @@ def _start_application(config: Configuration):
     dev_logger.info(f'Using {config.auth_config.__class__.__name__} auth configuration')
     auth_registry.register('auth_config', config.auth_config)
 
+    # Handle pages/router compatibility
+    if len(config.pages) > 0:
+        if len(config.router.children) > 0:
+            raise ValueError(
+                'ConfigurationBuilder.add_page is not compatible with the ConfigurationBuilder.router, `add_page` is supported for backwards compatibility but the recommended API going forward is using `config.router` directly.'
+            )
+
+        try:
+            eng_logger.info('Registering template')
+
+            # Add the default templates
+            if config.template == 'default':
+                eng_logger.info('Registering template "default"')
+                config.router = convert_template_to_router(default_template(config))
+            elif config.template == 'blank':
+                eng_logger.info('Registering template "blank"')
+                config.router = convert_template_to_router(blank_template(config))
+            elif config.template == 'top':
+                eng_logger.info('Registering template "top"')
+                config.router = convert_template_to_router(top_template(config))
+            elif config.template == 'top-menu':
+                eng_logger.info('Registering template "top-menu"')
+                config.router = convert_template_to_router(top_menu_template(config))
+            else:
+                # Loop over user defined templates and add to the registry
+                for name, renderer in config.template_renderers.items():
+                    if name == config.template:
+                        eng_logger.info(f'Registering custom template "{name}"')
+                        config.router = convert_template_to_router(renderer(config))
+                        break
+                else:
+                    raise ValueError(f'Unknown template renderer: {config.template}')
+        except Exception as e:
+            traceback.print_exc()
+            dev_logger.error(
+                'Something went wrong when building application template, there is most likely an issue in the application logic',
+                e,
+            )
+            sys.exit(1)
+
+    # Generate a new build_cache
     try:
-        eng_logger.info('Registering template')
-
-        # Add the default templates
-        if config.template == 'default':
-            eng_logger.info('Registering template "default"')
-            template_registry.register('default', default_template(config))
-        elif config.template == 'blank':
-            eng_logger.info('Registering template "blank"')
-            template_registry.register('blank', blank_template(config))
-        elif config.template == 'top':
-            eng_logger.info('Registering template "top"')
-            template_registry.register('top', top_template(config))
-        elif config.template == 'top-menu':
-            eng_logger.info('Registering template "top-menu"')
-            template_registry.register('top-menu', top_menu_template(config))
-        else:
-            # Loop over user defined templates and add to the registry
-            for name, renderer in config.template_renderers.items():
-                if name == config.template:
-                    eng_logger.info(f'Registering custom template "{name}"')
-                    template_registry.register(name, renderer(config))
+        build_cache = BuildCache.from_config(config)
+        build_diff = build_cache.get_diff()
 
+        # Only build if there's pages to build, otherwise assume Dara is only used for API
+        if len(config.router.children) > 0:
+            dev_logger.debug(
+                'Building JS...',
+                extra={
+                    'New build cache': build_cache.model_dump(),
+                    'Difference from last cache': build_diff.model_dump(),
+                },
+            )
+            rebuild_js(build_cache, build_diff)
     except Exception as e:
-        import traceback
-
         traceback.print_exc()
-        dev_logger.error(
-            'Something went wrong when building application template, there is most likely an issue in the application logic',
-            e,
-        )
+        dev_logger.error('Error building JS', error=e)
         sys.exit(1)
 
     # Root routes
@@ -352,42 +370,147 @@ def _start_application(config: Configuration):
         start_pprof_server(port=profiling_port)
 
     # Serve statics, only if we have any pages defined
-    if len(config.pages) > 0:
-        app.mount('/static', StaticFiles(directory=config.static_files_dir), name='static')
+    if len(config.router.children) > 0:
+        app.mount('/static', CacheStaticFiles(directory=config.static_files_dir), name='static')
 
     # Mount Routers
     app.include_router(auth_router, prefix='/api/auth')
     app.include_router(core_api_router, prefix='/api/core')
 
-    @app.get('/api/{rest_of_path:path}')
-    async def not_found():
-        raise HTTPException(status_code=404, detail='API endpoint not found')
+    if len(config.router.children) > 0:
+        BASE_DIR = Path(__file__).parent
+        jinja_templates = Jinja2Templates(directory=str(Path(BASE_DIR, 'jinja')))
+        jinja_templates.env.globals['vite_hmr_client'] = fastapi_vite_dara.vite_hmr_client
+        jinja_templates.env.globals['vite_asset'] = fastapi_vite_dara.vite_asset
+        jinja_templates.env.globals['static_url'] = fastapi_vite_dara.config.settings.static_url
+        jinja_templates.env.globals['base_url'] = os.getenv('DARA_BASE_URL', '')
+        jinja_templates.env.globals['entry'] = '_entry.tsx'
+
+        # Compile the router, executing all page functions etc
+        try:
+            config.router.compile()
+        except Exception as e:
+            traceback.print_exc()
+            dev_logger.error('Error compiling router', error=e)
+            sys.exit(1)
+
+        dev_logger.info('Registering pages:')
+        # TODO: convert this to use the logger?
+        config.router.print_route_tree()
+        route_map = config.router.to_route_map()
+
+        class ActionPayload(BaseModel):
+            uid: str
+            definition_uid: str
+            values: NormalizedPayload[Mapping[str, Any]]
+
+        class RouteDataRequestBody(BaseModel):
+            action_payloads: List[ActionPayload] = Field(default_factory=list)
+            ws_channel: Optional[str] = None
+            params: Dict[str, str] = Field(default_factory=dict)
+
+        @app.post('/api/core/route/{route_id}', dependencies=[Depends(verify_session)])
+        async def get_route_data(route_id: Annotated[str, PathParam()], body: Annotated[RouteDataRequestBody, Body()]):
+            # unquote route_id since it can be url-encoded
+            route_id = unquote(route_id)
+
+            # TODO: This will accept DV inputs etc and stream those back
+            route_data = route_map.get(route_id)
+
+            if route_data is None:
+                raise HTTPException(status_code=404, detail=f'Route {route_id} not found')
+
+            action_results: Dict[str, Any] = {}
+
+            if len(body.action_payloads) > 0:
+                store: CacheStore = utils_registry.get('Store')
+                task_mgr: TaskManager = utils_registry.get('TaskManager')
+                registry_mgr: RegistryLookup = utils_registry.get('RegistryLookup')
+
+                # Ws channel can be null for top-level layouts rendered above the ws client
+                if body.ws_channel is not None:
+                    WS_CHANNEL.set(body.ws_channel)
+
+                # Run actions in order to guarantee execution order
+                for action_payload in body.action_payloads:
+                    action_def = await registry_mgr.get(action_registry, action_payload.definition_uid)
+                    static_kwargs = await registry_mgr.get(static_kwargs_registry, action_payload.uid)
+
+                    CURRENT_ACTION_ID.set(action_payload.uid)
+                    values = denormalize(action_payload.values.data, action_payload.values.lookup)
+                    try:
+                        action_results[action_payload.uid] = await execute_action_sync(
+                            action_def,
+                            inp={'params': body.params, 'route': route_data.definition},
+                            values=values,
+                            static_kwargs=static_kwargs,
+                            store=store,
+                            task_mgr=task_mgr,
+                        )
+                    except BaseException as e:
+                        assert route_data.definition is not None
+                        route_path = route_data.definition.full_path
+                        action_name = str(action_def.resolver)
+                        raise HTTPException(
+                            status_code=500,
+                            detail={
+                                'error': str(e),
+                                'stacktrace': print_stacktrace(e),
+                                'path': route_path,
+                                'action_name': action_name,
+                            },
+                        ) from e
+
+            normalized_template, lookup = normalize(jsonable_encoder(route_data.content))
+            return {'template': {'data': normalized_template, 'lookup': lookup}, 'action_results': action_results}
+
+        # Catch-all, must add after adding the last api route
+        @app.get('/api/{rest_of_path:path}')
+        async def not_found():
+            raise HTTPException(status_code=404, detail='API endpoint not found')
+
+        # Prepare static template data
+        template_data = {
+            'auth_components': config.auth_config.component_config.model_dump(),
+            'actions': action_def_registry.get_all().items(),
+            'components': {k: comp.model_dump(exclude={'func'}) for k, comp in component_registry.get_all().items()},
+            'application_name': get_settings().project_name,
+            'enable_devtools': config.enable_devtools,
+            'live_reload': config.live_reload,
+            # TODO: this will become some backendstore-variable instead, prepopulated in here
+            'theme': config.theme,
+            'title': config.title,
+            'context_components': config.context_components,
+            # For backwards compatibility
+            'powered_by_causalens': config.powered_by_causalens,
+            'router': config.router,
+            'build_mode': build_cache.build_config.mode,
+            'build_dev': build_cache.build_config.dev,
+        }
+        json_template_data = json.dumps(jsonable_encoder(template_data))
 
-    if len(config.pages) > 0:
-        dev_logger.info(f'Registering pages: [{", ".join(list(config.pages.keys()))}]')
         # For any unmatched route then serve the app to the user if we have any pages to serve
         # (Required for the chosen routing system in the UI)
 
+        context = {
+            'dara_data': json_template_data,
+        }
+        template_name = 'index.html'
+
         # Auto-js mode - serve the built template with UMDs
         if build_cache.build_config.mode == BuildMode.AUTO_JS:
-            # Load template
-            template_path = os.path.join(Path(BASE_DIR, 'jinja'), 'index_autojs.html')  # type: ignore
-            with open(template_path, encoding='utf-8') as fp:
-                template = fp.read()
-
-            # Generate tags for the template
-            template = build_autojs_template(template, build_cache, config)
+            template_name = 'index_autojs.html'
+            context.update(build_autojs_template(build_cache, config))
 
-            @app.get('/{full_path:path}', include_in_schema=False, response_class=HTMLResponse)
-            async def serve_app(request: Request):  # pyright: ignore[reportRedeclaration]
-                return HTMLResponse(template)
+        @app.get('/{full_path:path}', include_in_schema=False, response_class=_TemplateResponse)
+        async def serve_app(request: Request):
+            return jinja_templates.TemplateResponse(request, template_name, context=context)
 
-        else:
-            # Otherwise serve the Vite template
-
-            @app.get('/{full_path:path}', include_in_schema=False, response_class=_TemplateResponse)
-            async def serve_app(request: Request):  # pyright: ignore[reportRedeclaration]
-                return jinja_templates.TemplateResponse(request, 'index.html')  # type: ignore
+    else:
+        # Catch-all, must be at the very end
+        @app.get('/api/{rest_of_path:path}')
+        async def not_found():
+            raise HTTPException(status_code=404, detail='API endpoint not found')
 
     return app
 

dara/core/router/__init__.py

@@ -0,0 +1,4 @@
+# ruff: noqa: F403
+from .compat import *
+from .components import *
+from .router import *

dara/core/router/compat.py

@@ -0,0 +1,77 @@
+from typing import List
+
+from dara.core.definitions import ComponentInstance
+
+from .components import Outlet
+from .router import Router
+
+
+def convert_template_to_router(template):
+    """
+    Convert old template system to new Router structure.
+
+    The conversion maps:
+    - Template.layout becomes the content of a root LayoutRoute, but with transformations:
+      - RouterContent components are replaced with Outlet components
+      - RouterContent.routes are extracted and become PageRoute/IndexRoute children
+    - Routes with route='/' become IndexRoute, others become PageRoute
+    - Route paths are normalized (leading slashes removed)
+
+    :param template: Template object with layout component containing RouterContent
+    :return: Router instance with converted structure
+    """
+    from dara.core.definitions import TemplateRouterContent
+    from dara.core.visual.components.router_content import RouterContent
+
+    router = Router()
+    extracted_routes: List[TemplateRouterContent] = []
+
+    # Transform the layout: replace RouterContent with Outlet and extract routes
+    def transform_component(component):
+        """Recursively transform components, replacing RouterContent with Outlet"""
+        # For other components, recursively transform their children/content
+        if isinstance(component, ComponentInstance):
+            if isinstance(component, RouterContent):
+                extracted_routes.extend(component.routes)
+                return Outlet()
+
+            for attr in component.model_fields_set:
+                value = getattr(component, attr, None)
+                if isinstance(value, ComponentInstance):
+                    setattr(component, attr, transform_component(value))
+                elif isinstance(value, list) and len(value) > 0 and isinstance(value[0], ComponentInstance):
+                    setattr(component, attr, [transform_component(item) for item in value])
+
+        return component
+
+    # Create root layout route using transformed template layout
+    root_layout = router.add_layout(content=transform_component(template.layout))
+
+    # Convert extracted routes to appropriate route types
+    for route_content in extracted_routes:
+        # Normalize route path: remove leading slash and handle root
+        route_path = route_content.route
+        if route_path.startswith('/'):
+            route_path = route_path[1:]
+
+        # NOTE: here it's safe to use the name as the id, as in the old api the name was unique
+        # but use 'index' for empty strings
+
+        # Root path becomes index route
+        if route_path in {'', '/'}:
+            root_layout.add_index(
+                content=route_content.content,
+                name=route_content.name,
+                id=route_content.name or 'index',
+                on_load=route_content.on_load,
+            )
+        else:
+            root_layout.add_page(
+                path=route_path,
+                content=route_content.content,
+                name=route_content.name,
+                id=route_content.name or 'index',
+                on_load=route_content.on_load,
+            )
+
+    return router

dara/core/router/components.py

@@ -0,0 +1,109 @@
+from typing import Annotated, Any, Literal, Optional, Union
+
+from pydantic import BaseModel, BeforeValidator
+
+from dara.core.definitions import ComponentInstance, JsComponentDef, StyledComponentInstance, transform_raw_css
+
+
+class RouterPath(BaseModel):
+    path: str
+    """
+    A URL pathname, beginning with '/'.
+    """
+
+    search: Optional[str] = None
+    """
+    A URL search string, beginning with '?'.
+    """
+
+    hash: Optional[str] = None
+    """
+    A URL hash string, beginning with '#'.
+    """
+
+
+OutletDef = JsComponentDef(name='Outlet', js_module='@darajs/core', py_module='dara.core')
+
+
+class Outlet(ComponentInstance):
+    """
+    Outlet component is a placeholder for the content of the current route.
+    """
+
+
+LinkDef = JsComponentDef(name='Link', js_module='@darajs/core', py_module='dara.core')
+
+
+class Link(StyledComponentInstance):
+    """
+    Link component is a wrapper around the NavLink component that displays a link to the specified route.
+    """
+
+    case_sensitive: bool = False
+
+    end: bool = True
+    """
+    Changes the matching logic for the 'active' state to only match the end of the 'to' prop.
+    If the URL is longer, it will not be considered active. Defaults to True.
+
+    For example, NavLink(to='/tasks') while on '/tasks/123' will:
+    - with `end=False`, be considered active because of the partial match of the `/tasks` part
+    - with `end=True`, be considered inactive because of the missing '123' part
+    """
+
+    # TODO: not implemented yet
+    # prefetch: Literal['none', 'intent', 'render', 'viewport'] = 'none'
+    # """
+    # Defines the data and module prefetching behavior for the link.
+    # - none — default, no prefetching
+    # - intent — prefetches when the user hovers or focuses the link
+    # - render — prefetches when the link renders
+    # - viewport — prefetches when the link is in the viewport, very useful for mobile
+    # """
+
+    relative: Literal['route', 'path'] = 'route'
+    """
+    Defines the relative path behavior for the link.
+
+    ```python
+    Link(to='..') # default, relative='route'
+    Link(to='..', relative='path')
+    ```
+
+    Consider a route hierarchy where a parent route pattern is "blog" and a child route pattern is "blog/:slug/edit".
+    - route — default, resolves the link relative to the route pattern. In the example above, a relative link of "..." will remove both :slug/edit segments back to "/blog".
+    - path — relative to the path so "..." will only remove one URL segment up to "/blog/:slug"
+    Note that index routes and layout routes do not have paths so they are not included in the relative path calculation.
+    """
+
+    replace: bool = False
+    """
+    Replaces the current entry in the history stack instead of pushing a new one.
+
+    ```
+    # with a history stack like this
+    A -> B
+
+    # normal link click pushes a new entry
+    A -> B -> C
+
+    # but with `replace`, B is replaced by C
+    A -> C
+    ```
+    """
+
+    to: Union[str, RouterPath]
+    """
+    Can be a string or RouterPath object
+    """
+
+    active_css: Annotated[Optional[Any], BeforeValidator(transform_raw_css)] = None
+    inactive_css: Annotated[Optional[Any], BeforeValidator(transform_raw_css)] = None
+
+    # TODO: add scroll restoration if it works?
+
+    def __init__(self, *children: ComponentInstance, **kwargs):
+        components = list(children)
+        if 'children' not in kwargs:
+            kwargs['children'] = components
+        super().__init__(**kwargs)