meerschaum 2.9.5__py3-none-any.whl → 3.0.0rc1__py3-none-any.whl

meerschaum/api/__init__.py

@@ -14,7 +14,7 @@ from fnmatch import fnmatch
 import meerschaum as mrsm
 from meerschaum.utils.typing import Dict, Any, Optional, PipesDict
 from meerschaum.config import get_config
-from meerschaum.config.static import STATIC_CONFIG, SERVER_ID
+from meerschaum._internal.static import STATIC_CONFIG, SERVER_ID
 from meerschaum.utils.packages import attempt_import
 from meerschaum.utils import get_pipes as _get_pipes
 from meerschaum.config._paths import API_UVICORN_CONFIG_PATH, API_UVICORN_RESOURCES_PATH
@@ -95,10 +95,12 @@ def get_uvicorn_config() -> Dict[str, Any]:
 
 debug = get_uvicorn_config().get('debug', False)
 no_dash = get_uvicorn_config().get('no_dash', False)
+no_webterm = get_uvicorn_config().get('no_webterm', False)
 no_auth = get_uvicorn_config().get('no_auth', False)
 private = get_uvicorn_config().get('private', False)
 production = get_uvicorn_config().get('production', False)
 _include_dash = (not no_dash)
+_include_webterm = (not no_webterm) and _include_dash
 docs_enabled = not production or sys_config.get('endpoints', {}).get('docs_in_production', True)
 
 default_instance_keys = None
@@ -210,6 +212,11 @@ def get_pipe(
     if location_key in ('[None]', 'None', 'null'):
         location_key = None
     instance_keys = str(get_api_connector(instance_keys))
+    if connector_keys == 'mrsm':
+        raise fastapi.HTTPException(
+            status_code=403,
+            detail="Unable to serve any pipes with connector keys `mrsm` over the API.",
+        )
     pipe = mrsm.Pipe(connector_keys, metric_key, location_key, mrsm_instance=instance_keys)
     if is_pipe_registered(pipe, pipes(instance_keys)):
         return pipes(instance_keys, refresh=refresh)[connector_keys][metric_key][location_key]
@@ -291,7 +298,7 @@ def __getattr__(name: str):
     raise AttributeError(f"Could not import '{name}'.")
 
 ### Import everything else within the API.
-from meerschaum.api._oauth2 import manager
+from meerschaum.api._oauth2 import manager, ScopedAuth
 import meerschaum.api.routes as routes
 import meerschaum.api._events
 import meerschaum.api._websockets

meerschaum/api/_events.py

@@ -16,6 +16,8 @@ from meerschaum.api import (
     get_uvicorn_config,
     debug,
     no_dash,
+    _include_dash,
+    _include_webterm,
 )
 from meerschaum.utils.debug import dprint
 from meerschaum.connectors.poll import retry_connect
@@ -25,7 +27,7 @@ from meerschaum.jobs import (
     start_check_jobs_thread,
     stop_check_jobs_thread,
 )
-from meerschaum.config.static import STATIC_CONFIG
+from meerschaum._internal.static import STATIC_CONFIG
 
 TEMP_PREFIX: str = STATIC_CONFIG['api']['jobs']['temp_prefix']
 
@@ -35,8 +37,43 @@ async def startup():
     """
     Connect to the instance database and begin monitoring jobs.
     """
+    app.openapi_schema = app.openapi()
+
+    ### Remove the implicitly added HTTPBearer scheme if it exists.
+    if 'BearerAuth' in app.openapi_schema['components']['securitySchemes']:
+        del app.openapi_schema['components']['securitySchemes']['BearerAuth']
+    elif 'HTTPBearer' in app.openapi_schema['components']['securitySchemes']:
+        del app.openapi_schema['components']['securitySchemes']['HTTPBearer']
+    if 'LoginManager' in app.openapi_schema['components']['securitySchemes']:
+        del app.openapi_schema['components']['securitySchemes']['LoginManager']
+
+    scopes = STATIC_CONFIG['tokens']['scopes']
+    app.openapi_schema['components']['securitySchemes']['OAuth2PasswordBearer'] = {
+        'type': 'oauth2',
+        'flows': {
+            'password': {
+                'tokenUrl': STATIC_CONFIG['api']['endpoints']['login'],
+                'scopes': scopes,
+            },
+        },
+    }
+    app.openapi_schema['components']['securitySchemes']['APIKey'] = {
+        'type': 'http',
+        'scheme': 'bearer',
+        'bearerFormat': 'mrsm-key:{client_id}:{client_secret}',
+        'description': 'Authentication using a Meerschaum API Key.',
+    }
+    app.openapi_schema['security'] = [
+        {
+            'OAuth2PasswordBearer': [],
+        },
+        {
+            'APIKey': [],
+        }
+    ]
+
     try:
-        if not no_dash:
+        if _include_webterm:
             from meerschaum.api.dash.webterm import start_webterm
             start_webterm()
 

meerschaum/api/_oauth2.py

@@ -7,21 +7,34 @@ Define JWT authorization here.
 """
 
 import os
-from meerschaum.api import app, endpoints, CHECK_UPDATE
+import base64
+import functools
+import inspect
+from typing import List, Optional, Union
+
+from meerschaum.api import endpoints, CHECK_UPDATE, no_auth, debug
+from meerschaum.api._tokens import optional_token, get_token_from_authorization
+from meerschaum._internal.static import STATIC_CONFIG
 from meerschaum.utils.packages import attempt_import
-fastapi = attempt_import('fastapi', lazy=False, check_update=CHECK_UPDATE)
+from meerschaum.core import User, Token
+
+fastapi, starlette = attempt_import('fastapi', 'starlette', lazy=False, check_update=CHECK_UPDATE)
 fastapi_responses = attempt_import('fastapi.responses', lazy=False, check_update=CHECK_UPDATE)
 fastapi_login = attempt_import('fastapi_login', check_update=CHECK_UPDATE)
+from fastapi import Depends, HTTPException, Request
+from starlette import status
+
 
 class CustomOAuth2PasswordRequestForm:
     def __init__(
         self,
         grant_type: str = fastapi.Form(None, regex="password|client_credentials"),
-        username: str = fastapi.Form(...),
-        password: str = fastapi.Form(...),
-        scope: str = fastapi.Form(""),
-        client_id: str = fastapi.Form(None),
-        client_secret: str = fastapi.Form(None),
+        username: Optional[str] = fastapi.Form(None),
+        password: Optional[str] = fastapi.Form(None),
+        scope: str = fastapi.Form(" ".join(STATIC_CONFIG['tokens']['scopes'])),
+        client_id: Optional[str] = fastapi.Form(None),
+        client_secret: Optional[str] = fastapi.Form(None),
+        authorization: Optional[str] = fastapi.Header(None),
     ):
         self.grant_type = grant_type
         self.username = username
@@ -30,9 +43,106 @@ class CustomOAuth2PasswordRequestForm:
         self.client_id = client_id
         self.client_secret = client_secret
 
+        if (
+            not username
+            and not password
+            and not self.client_id
+            and not self.client_secret
+            and authorization
+        ):
+            try:
+                scheme, credentials = authorization.split()
+                if credentials.startswith('mrsm-key:'):
+                    credentials = credentials[len('mrsm-key:'):]
+                if scheme.lower() in ('basic', 'bearer'):
+                    decoded_credentials = base64.b64decode(credentials).decode('utf-8')
+                    _client_id, _client_secret = decoded_credentials.split(':', 1)
+                    self.client_id = _client_id
+                    self.client_secret = _client_secret
+                    self.grant_type = 'client_credentials'
+            except ValueError:
+                pass
+
+
+async def optional_user(request: Request) -> Optional[User]:
+    """
+    FastAPI dependency that returns a User if logged in, otherwise None.
+    """
+    if no_auth:
+        return None
+    return await manager(request)
+    try:
+        return await manager(request)
+    except HTTPException:
+        return None
+
+
+async def load_user_or_token(
+    request: Request,
+    users: bool = True,
+    tokens: bool = True,
+) -> Union[User, Token, None]:
+    """
+    Load the current user or token.
+    """
+    authorization = request.headers.get('authorization', request.headers.get('Authorization', None))
+    if not authorization:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated.",
+        )
+    authorization = authorization.replace('Basic ', '').replace('Bearer ', '')
+    if not authorization.startswith('mrsm-key:'):
+        if not users:
+            raise HTTPException(
+                status=status.HTTP_401_UNAUTHORIZED,
+                detail="Users not authenticated for this endpoint.",
+            )
+        return await manager(request)
+    if not tokens:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Tokens not authenticated for this endpoint.",
+        )
+    return get_token_from_authorization(authorization)
+
+
+def ScopedAuth(scopes: List[str]):
+    """
+    Dependency factory for authenticating with either a user session or a scoped token.
+    """
+    async def _authenticate(
+        user_or_token: Union[User, Token, None] = Depends(
+            load_user_or_token,
+        ),
+    ) -> Union[User, Token, None]:
+        if no_auth:
+            return None
+
+        if not user_or_token:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Not authenticated.",
+                headers={"WWW-Authenticate": "Basic"},
+            )
+
+        fresh_scopes = user_or_token.get_scopes(refresh=True, debug=debug)
+        if '*' in fresh_scopes:
+            return user_or_token
+
+        for scope in scopes:
+            if scope not in fresh_scopes:
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail=f"Missing required scope: '{scope}'",
+                )
+        
+        return user_or_token
+    return _authenticate
+
 
 LoginManager = fastapi_login.LoginManager
-def generate_secret_key() -> str:
+def generate_secret_key() -> bytes:
     """
     Read or generate the secret keyfile.
     """

meerschaum/api/_tokens.py

@@ -0,0 +1,102 @@
+#! /usr/bin/env python3
+# vim:fenc=utf-8
+
+"""
+Define the authentication logic for Meerschaum Tokens.
+"""
+
+import base64
+import uuid
+from typing import Optional, Union, List
+from datetime import datetime, timezone
+
+from fastapi import Depends, HTTPException, Request
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from starlette import status
+
+import meerschaum as mrsm
+from meerschaum.api import (
+    get_api_connector,
+    debug,
+)
+from meerschaum.core import Token, User
+from meerschaum.core.User import verify_password
+
+
+http_bearer = HTTPBearer(auto_error=False, scheme_name="APIKey")
+
+
+def get_token_from_authorization(authorization: str) -> Token:
+    """
+    Helper function to decode and verify a token from credentials.
+    Raises HTTPException on failure.
+    """
+    if authorization.startswith('mrsm-key:'):
+        authorization = authorization[len('mrsm-key:'):]
+    try:
+        credential_string = base64.b64decode(authorization).decode('utf-8')
+        token_id_str, secret = credential_string.split(':', 1)
+        token_id = uuid.UUID(token_id_str)
+    except Exception:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token format. Expected Base64-encoded 'token_id:secret'.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    conn = get_api_connector()
+    token = conn.get_token(token_id)
+
+    if not token or not token.is_valid:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or revoked token.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if token.get_expiration_status(debug=debug):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Token has expired.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if not verify_password(secret, token.secret_hash):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid secret.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    return token
+
+
+def get_current_token(
+    auth_creds: Optional[HTTPAuthorizationCredentials] = Depends(http_bearer),
+) -> Token:
+    """
+    FastAPI dependency to authenticate a request with a Meerschaum Token.
+    This dependency will fail if no token is provided.
+    """
+    if auth_creds is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return get_token_from_authorization(auth_creds.credentials)
+
+
+async def optional_token(
+    auth_creds: Optional[HTTPAuthorizationCredentials] = Depends(http_bearer),
+) -> Optional[Token]:
+    """
+    FastAPI dependency that returns a Token if provided, otherwise None.
+    """
+    if not auth_creds:
+        return None
+
+    try:
+        return get_token_from_authorization(auth_creds.credentials)
+    except HTTPException as e:
+        return None

meerschaum/api/dash/__init__.py

@@ -19,7 +19,6 @@ _monkey_patch_get_distribution('flask-compress', flask_compress.__version__)
 dash = attempt_import('dash', lazy=False)
 
 from meerschaum.utils.typing import List, Optional
-from meerschaum.config.static import _static_config
 from meerschaum.api import (
     app as fastapi_app,
     debug,

meerschaum/api/dash/callbacks/custom.py

@@ -36,9 +36,9 @@ def add_plugin_pages(debug: bool = False):
     """
     Allow users to add pages via the `@web_page` decorator.
     """
-    for plugin_name, pages_dicts in _plugin_endpoints_to_pages.items():
+    for page_group, pages_dicts in _plugin_endpoints_to_pages.items():
         if debug:
-            dprint(f"Adding pages from plugin '{plugin_name}'...")
+            dprint(f"Adding pages for group '{page_group}'...")
         for _endpoint, _page_dict in pages_dicts.items():
             page_layout = _page_dict['function']()
             if not _page_dict['skip_navbar']:

meerschaum/api/dash/callbacks/dashboard.py

@@ -11,10 +11,11 @@ from __future__ import annotations
 import textwrap
 import json
 import uuid
-from datetime import datetime, timezone
 
 from dash.dependencies import Input, Output, State, ALL, MATCH
 from dash.exceptions import PreventUpdate
+
+import meerschaum as mrsm
 from meerschaum.utils.typing import List, Optional, Any, Tuple
 from meerschaum.api import get_api_connector, endpoints, no_auth, CHECK_UPDATE
 from meerschaum.api.dash import dash_app, debug
@@ -26,7 +27,12 @@ from meerschaum.api.dash.sessions import (
 from meerschaum.api.dash.sessions import is_session_authenticated
 from meerschaum.api.dash.connectors import get_web_connector
 from meerschaum.connectors.parse import parse_instance_keys
-from meerschaum.api.dash.pipes import get_pipes_cards, pipe_from_ctx, accordion_items_from_pipe
+from meerschaum.api.dash.pipes import (
+    get_pipes_cards,
+    pipe_from_ctx,
+    accordion_items_from_pipe,
+    get_backtrack_text,
+)
 from meerschaum.api.dash.jobs import get_jobs_cards
 from meerschaum.api.dash.plugins import get_plugins_cards
 from meerschaum.api.dash.users import get_users_cards
@@ -41,7 +47,7 @@ from meerschaum.api.dash.components import (
 from meerschaum.api.dash import pages
 from meerschaum.utils.typing import Dict
 from meerschaum.utils.packages import attempt_import, import_html, import_dcc
-from meerschaum.utils.misc import filter_keywords, flatten_list
+from meerschaum.utils.misc import filter_keywords, flatten_list, string_to_dict
 from meerschaum.utils.yaml import yaml
 from meerschaum.actions import get_subactions, actions
 from meerschaum._internal.arguments._parser import parser
@@ -55,11 +61,8 @@ keys_state = (
     State('connector-keys-dropdown', 'value'),
     State('metric-keys-dropdown', 'value'),
     State('location-keys-dropdown', 'value'),
-    State('connector-keys-input', 'value'),
-    State('metric-keys-input', 'value'),
-    State('location-keys-input', 'value'),
-    State('search-parameters-editor', 'value'),
-    State('pipes-filter-tabs', 'active_tab'),
+    State('tags-dropdown', 'value'),
+    State('tags-dropdown-div', 'style'),
     State('action-dropdown', 'value'),
     State('subaction-dropdown', 'value'),
     State('subaction-dropdown', 'options'),
@@ -295,6 +298,7 @@ dash_app.clientside_callback(
         connector_keys,
         metric_keys,
         location_keys,
+        tags,
         flags,
         input_flags,
         input_flags_texts,
@@ -317,6 +321,7 @@ dash_app.clientside_callback(
                 connector_keys: connector_keys,
                 metric_keys: metric_keys,
                 location_keys: location_keys,
+                tags: tags,
                 flags: flags,
                 input_flags: input_flags,
                 input_flags_texts: input_flags_texts,
@@ -333,6 +338,7 @@ dash_app.clientside_callback(
     State('connector-keys-dropdown', 'value'),
     State('metric-keys-dropdown', 'value'),
     State('location-keys-dropdown', 'value'),
+    State('tags-dropdown', 'value'),
     State('flags-dropdown', 'value'),
     State({'type': 'input-flags-dropdown', 'index': ALL}, 'value'),
     State({'type': 'input-flags-dropdown-text', 'index': ALL}, 'value'),
@@ -358,7 +364,7 @@ def update_actions(action: str, subaction: str):
     _actions_options = sorted([
         {
             'label': a.replace('_', ' '),
-            'value': a,
+            'value': a.replace('_', ' '),
             'title': (textwrap.dedent(f.__doc__).lstrip() if f.__doc__ else 'No help available.'),
         }
         for a, f in actions.items() if a not in omit_actions
@@ -366,7 +372,7 @@ def update_actions(action: str, subaction: str):
     _subactions_options = sorted([
         {
             'label': sa.replace('_', ' '),
-            'value': sa,
+            'value': sa.replace('_', ' '),
             'title': (textwrap.dedent(f.__doc__).lstrip() if f.__doc__ else 'No help available.'),
         }
         for sa, f in get_subactions(action).items()
@@ -497,11 +503,15 @@ def update_flags(input_flags_dropdown_values, n_clicks, input_flags_texts):
     Output('location-keys-dropdown', 'options'),
     Output('location-keys-list', 'children'),
     Output('location-keys-dropdown', 'value'),
+    Output('tags-dropdown', 'options'),
+    Output('tags-list', 'children'),
+    Output('tags-dropdown', 'value'),
     Output('instance-select', 'value'),
     Output('instance-alert-div', 'children'),
     Input('connector-keys-dropdown', 'value'),
     Input('metric-keys-dropdown', 'value'),
     Input('location-keys-dropdown', 'value'),
+    Input('tags-dropdown', 'value'),
     Input('instance-select', 'value'),
     *keys_state  ### NOTE: Necessary for `ctx.states`.
 )
@@ -509,6 +519,7 @@ def update_keys_options(
     connector_keys: Optional[List[str]],
     metric_keys: Optional[List[str]],
     location_keys: Optional[List[str]],
+    tags: Optional[List[str]],
     instance_keys: Optional[str],
     *keys
 ):
@@ -543,6 +554,8 @@ def update_keys_options(
         metric_keys = []
     if location_keys is None:
         location_keys = []
+    if tags is None:
+        tags = []
     num_filter = 0
     if connector_keys:
         num_filter += 1
@@ -550,13 +563,17 @@ def update_keys_options(
         num_filter += 1
     if location_keys:
         num_filter += 1
+    if tags:
+        num_filter += 1
 
     _ck_filter = connector_keys
     _mk_filter = metric_keys
     _lk_filter = location_keys
+    _tags_filter = tags
     _ck_alone = (connector_keys and num_filter == 1) or instance_click
     _mk_alone = (metric_keys and num_filter == 1) or instance_click
     _lk_alone = (location_keys and num_filter == 1) or instance_click
+    _tags_alone = (tags and num_filter == 1) or instance_click
 
     from meerschaum.utils import fetch_pipes_keys
 
@@ -568,15 +585,31 @@ def update_keys_options(
             connector_keys=_ck_filter,
             metric_keys=_mk_filter,
             location_keys=_lk_filter,
+            tags=_tags_filter,
+        )
+        _tags_pipes = mrsm.get_pipes(
+            connector_keys=_ck_filter,
+            metric_keys=_mk_filter,
+            location_keys=_lk_filter,
+            tags=_tags_filter,
+            instance=get_web_connector(ctx.states),
+            as_tags_dict=True,
         )
+        _all_tags = list(
+            mrsm.get_pipes(
+                instance=get_web_connector(ctx.states),
+                as_tags_dict=True,
+            )
+        ) if _tags_alone else []
     except Exception as e:
         instance_alerts += [alert_from_success_tuple((False, str(e)))]
         _all_keys, _keys = [], []
     _connectors_options = []
     _metrics_options = []
     _locations_options = []
+    _tags_options = []
 
-    _seen_keys = {'ck' : set(), 'mk' : set(), 'lk' : set()}
+    _seen_keys = {'ck' : set(), 'mk' : set(), 'lk' : set(), 'tags': set()}
 
     def add_options(options, keys, key_type):
         for ck, mk, lk in keys:
@@ -589,9 +622,16 @@ def update_keys_options(
     add_options(_connectors_options, _all_keys if _ck_alone else _keys, 'ck')
     add_options(_metrics_options, _all_keys if _mk_alone else _keys, 'mk')
     add_options(_locations_options, _all_keys if _lk_alone else _keys, 'lk')
+
+    _tags_options = [
+        {'label': tag, 'value': tag}
+        for tag in (_all_tags if _tags_alone else _tags_pipes)
+    ]
+
     _connectors_options.sort(key=lambda x: str(x).lower())
     _metrics_options.sort(key=lambda x: str(x).lower())
     _locations_options.sort(key=lambda x: str(x).lower())
+    _tags_options.sort(key=lambda x: str(x).lower())
     connector_keys = [
         ck
         for ck in connector_keys
@@ -616,9 +656,18 @@ def update_keys_options(
             for _lk in _locations_options
         ]
     ]
+    tags = [
+        tag
+        for tag in tags
+        if tag in [
+            _tag['value']
+            for _tag in _tags_options
+        ]
+    ]
     _connectors_datalist = [html.Option(value=o['value']) for o in _connectors_options]
     _metrics_datalist = [html.Option(value=o['value']) for o in _metrics_options]
     _locations_datalist = [html.Option(value=o['value']) for o in _locations_options]
+    _tags_datalist = [html.Option(value=o['value']) for o in _tags_options]
     return (
         _connectors_options,
         _connectors_datalist,
@@ -629,6 +678,9 @@ def update_keys_options(
         _locations_options,
         _locations_datalist,
         location_keys,
+        _tags_options,
+        _tags_datalist,
+        tags,
         (instance_keys if update_instance_keys else dash.no_update),
         instance_alerts,
     )
@@ -861,7 +913,6 @@ def update_pipe_accordion(item, session_store_data):
 def update_pipe_parameters_click(n_clicks, parameters_editor_text):
     if not n_clicks:
         raise PreventUpdate
-    ctx = dash.callback_context
     triggered = dash.callback_context.triggered
     if triggered[0]['value'] is None:
         raise PreventUpdate
@@ -890,12 +941,11 @@ def update_pipe_parameters_click(n_clicks, parameters_editor_text):
 @dash_app.callback(
     Output({'type': 'update-sql-success-div', 'index': MATCH}, 'children'),
     Input({'type': 'update-sql-button', 'index': MATCH}, 'n_clicks'),
-    State({'type': 'sql-editor', 'index': MATCH}, 'value')
+    State({'type': 'sql-editor', 'index': MATCH}, 'value'),
 )
 def update_pipe_sql_click(n_clicks, sql_editor_text):
     if not n_clicks:
         raise PreventUpdate
-    ctx = dash.callback_context
     triggered = dash.callback_context.triggered
     if triggered[0]['value'] is None:
         raise PreventUpdate
@@ -923,7 +973,6 @@ def update_pipe_sql_click(n_clicks, sql_editor_text):
 def sync_documents_click(n_clicks, sync_editor_text):
     if not n_clicks:
         raise PreventUpdate
-    ctx = dash.callback_context
     triggered = dash.callback_context.triggered
     if triggered[0]['value'] is None:
         raise PreventUpdate
@@ -937,6 +986,15 @@ def sync_documents_click(n_clicks, sync_editor_text):
     except Exception as e:
         docs = None
         msg = str(e)
+
+    if docs is None:
+        try:
+            lines = sync_editor_text.splitlines()
+            docs = [string_to_dict(line) for line in lines]
+            msg = '... '
+        except Exception:
+            docs = None
+
     if docs is None:
         success, msg = False, (msg + f"Unable to sync documents to {pipe}.")
     else:
@@ -1043,8 +1101,8 @@ dash_app.clientside_callback(
 
 @dash_app.callback(
     Output("navbar-collapse", "is_open"),
-    [Input("navbar-toggler", "n_clicks")],
-    [State("navbar-collapse", "is_open")],
+    Input("navbar-toggler", "n_clicks"),
+    State("navbar-collapse", "is_open"),
 )
 def toggle_navbar_collapse(n_clicks: Optional[int], is_open: bool) -> bool:
     """
@@ -1103,7 +1161,6 @@ def parameters_as_yaml_or_json_click(
     if not yaml_n_clicks and not json_n_clicks:
         raise PreventUpdate
 
-    ctx = dash.callback_context
     triggered = dash.callback_context.triggered
     if triggered[0]['value'] is None:
         raise PreventUpdate
@@ -1117,6 +1174,33 @@ def parameters_as_yaml_or_json_click(
     return json.dumps(pipe.parameters, indent=4, separators=(',', ': '), sort_keys=True)
 
 
+@dash_app.callback(
+    Output({'type': 'sync-editor', 'index': MATCH}, 'value'),
+    Input({'type': 'sync-as-json-button', 'index': MATCH}, 'n_clicks'),
+    Input({'type': 'sync-as-lines-button', 'index': MATCH}, 'n_clicks'),
+)
+def sync_as_json_or_lines_click(
+    json_n_clicks: Optional[int],
+    lines_n_clicks: Optional[int],
+):
+    """
+    When the `YAML` button is clicked under the parameters editor, switch the content to YAML.
+    """
+    if not json_n_clicks and not lines_n_clicks:
+        raise PreventUpdate
+
+    triggered = dash.callback_context.triggered
+    if triggered[0]['value'] is None:
+        raise PreventUpdate
+
+    as_lines = 'lines' in triggered[0]['prop_id']
+    pipe = pipe_from_ctx(triggered, 'n_clicks')
+    if pipe is None:
+        raise PreventUpdate
+
+    return get_backtrack_text(pipe, lines=as_lines)
+
+
 @dash_app.callback(
     Output('pages-offcanvas', 'is_open'),
     Output('pages-offcanvas', 'children'),