api-dock 0.7.0__tar.gz → 0.7.1__tar.gz

{api_dock-0.7.0 → api_dock-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api_dock
-Version: 0.7.0
+Version: 0.7.1
 Summary: A flexible API gateway that allows you to proxy requests to multiple remote APIs and Databases
 Author-email: Brookie Guzder-Williams <bguzder-williams@berkeley.edu>
 License-Expression: BSD-3-Clause
@@ -672,6 +672,125 @@ Parameters are processed in this order (first match wins for early returns):
 
 ---
 
+## Conditional SQL Selection
+
+Some routes need a *different* base query depending on the request — for example, `?count=true` should return a species histogram (`SELECT … COUNT(*) … GROUP BY …`) rather than rows. `sql_append` can't help (it only adds trailing clauses), and a second `route:` can't either (the path is identical). For this, a route's `sql` may be a **rule list** instead of a string: a first-match-wins decision tree that picks the base query from the presence and value of path, query, and cookie params.
+
+Everything downstream is unchanged: the selected base composes with `query_params` WHERE-fragments and `sql_append` exactly as a plain `sql:` string does.
+
+### The histogram example
+
+```yaml
+routes:
+  - route: detections
+    sql:
+      # ?count=<truthy>  → species histogram
+      - when: count
+        then:
+          sql: >
+            SELECT [[detections]].common_name, [[detections]].scientific_name,
+                   COUNT(*) AS count
+            FROM [[detections]]
+          sql_append: GROUP BY [[detections]].common_name, [[detections]].scientific_name
+      # otherwise → detection rows
+      - else: SELECT [[detections]].* FROM [[detections]]
+    query_params:
+      - recording:
+          sql: "[[detections]].recording_id = {{recording}}"
+          multivalue_sql: "[[detections]].recording_id IN {{recording}}"
+      - limit:
+          sql_append: LIMIT {{limit}}          # applies in BOTH modes
+```
+
+```bash
+GET /db/detections?recording=1&count=true
+# SELECT detections.common_name, detections.scientific_name, COUNT(*) AS count
+#   FROM detections WHERE detections.recording_id = '1'
+#   GROUP BY detections.common_name, detections.scientific_name
+
+GET /db/detections?recording=1
+# SELECT detections.* FROM detections WHERE detections.recording_id = '1'
+```
+
+Note the pipeline order: the selected branch's `sql_append` (the `GROUP BY`) is applied **before** route-level `sql_append` (the shared `LIMIT`), so SQL clause order stays valid.
+
+### Rule forms
+
+A `sql` list contains rules evaluated top to bottom; the **first match wins**. Each rule's payload (an *sql node*) is a SQL string, a leaf object `{sql, sql_append}`, or a nested rule list.
+
+```yaml
+sql:
+  - when: count                       # fires when `count` is truthy (shorthand for equals: _truthy)
+    then: <sql node>
+
+  - when: mode
+    equals: 'true'                    # fires only when mode == "true" (case-insensitive)
+    then: <sql node>
+
+  - when: format                      # value map: different SQL per value
+    match:
+      species: <sql node>             # ?format=species
+      recording: <sql node>           # ?format=recording
+      _truthy: <sql node>             # any other truthy value
+      _default: <sql node>            # any present value not matched above
+
+  - when: [count, recording]          # list: fires when ALL are truthy (AND)
+    then: <sql node>
+
+  - when: [count, something_else]     # list + positional case list
+    match:
+      - values: [_any, x]             # something_else == x, count anything
+        then: <sql node>
+      - values: [_truthy, _absent]    # count truthy AND something_else not passed
+        then: <sql node>
+      - default: <sql node>
+
+  - else: <sql node>                  # default (a trailing bare string works too)
+```
+
+Nesting works because a payload can itself be a rule list:
+
+```yaml
+sql:
+  - when: some_value
+    match:
+      '4':
+        - when: count
+          then: <sql for value 4 with count>
+        - else: <sql for value 4>
+      _default: <sql for other values>
+  - else: <base sql>
+```
+
+### Value specs
+
+| spec | matches when the param… |
+|---|---|
+| `'literal'` (`'4'`, `'true'`) | is present and equals it (case-insensitive) |
+| `_truthy` / `_falsy` | present, and value is / isn't in `{"", "0", "false", "no", "off", "null", "none"}` |
+| `_present` / `_absent` | exists / does not exist |
+| `_any` | wildcard — present or absent (used for a position in a case list) |
+| `_default` | catch-all for any *present* value (value maps only) |
+
+In a single-param `match:` map, precedence is order-independent: exact literal > `_falsy`/`_truthy` > `_present`/`_absent` > `_default`. In a positional case list, cases match strictly top-to-bottom.
+
+### No match → URL error
+
+If no rule matches and there is no default (`else`, a trailing bare string, or a `_default`/`default` catch-all), the request returns a **400** with `{"error": "No matching query configuration for the given parameters", "http_status": 400}`. Customize it with a terminal `no_match` rule:
+
+```yaml
+sql:
+  - when: recording
+    then: SELECT [[detections]].* FROM [[detections]] WHERE recording_id = {{recording}}
+  - no_match:
+      error: "recording is required, or pass count=true for a histogram"
+      http_status: 400
+```
+
+Cookies participate via the `cookies.<name>` key (e.g. `when: cookies.role`, `equals: admin`).
+
+---
+
 # CLI
 
 ## Commands

{api_dock-0.7.0 → api_dock-0.7.1}/README.md

@@ -633,6 +633,125 @@ Parameters are processed in this order (first match wins for early returns):
 
 ---
 
+## Conditional SQL Selection
+
+Some routes need a *different* base query depending on the request — for example, `?count=true` should return a species histogram (`SELECT … COUNT(*) … GROUP BY …`) rather than rows. `sql_append` can't help (it only adds trailing clauses), and a second `route:` can't either (the path is identical). For this, a route's `sql` may be a **rule list** instead of a string: a first-match-wins decision tree that picks the base query from the presence and value of path, query, and cookie params.
+
+Everything downstream is unchanged: the selected base composes with `query_params` WHERE-fragments and `sql_append` exactly as a plain `sql:` string does.
+
+### The histogram example
+
+```yaml
+routes:
+  - route: detections
+    sql:
+      # ?count=<truthy>  → species histogram
+      - when: count
+        then:
+          sql: >
+            SELECT [[detections]].common_name, [[detections]].scientific_name,
+                   COUNT(*) AS count
+            FROM [[detections]]
+          sql_append: GROUP BY [[detections]].common_name, [[detections]].scientific_name
+      # otherwise → detection rows
+      - else: SELECT [[detections]].* FROM [[detections]]
+    query_params:
+      - recording:
+          sql: "[[detections]].recording_id = {{recording}}"
+          multivalue_sql: "[[detections]].recording_id IN {{recording}}"
+      - limit:
+          sql_append: LIMIT {{limit}}          # applies in BOTH modes
+```
+
+```bash
+GET /db/detections?recording=1&count=true
+# SELECT detections.common_name, detections.scientific_name, COUNT(*) AS count
+#   FROM detections WHERE detections.recording_id = '1'
+#   GROUP BY detections.common_name, detections.scientific_name
+
+GET /db/detections?recording=1
+# SELECT detections.* FROM detections WHERE detections.recording_id = '1'
+```
+
+Note the pipeline order: the selected branch's `sql_append` (the `GROUP BY`) is applied **before** route-level `sql_append` (the shared `LIMIT`), so SQL clause order stays valid.
+
+### Rule forms
+
+A `sql` list contains rules evaluated top to bottom; the **first match wins**. Each rule's payload (an *sql node*) is a SQL string, a leaf object `{sql, sql_append}`, or a nested rule list.
+
+```yaml
+sql:
+  - when: count                       # fires when `count` is truthy (shorthand for equals: _truthy)
+    then: <sql node>
+
+  - when: mode
+    equals: 'true'                    # fires only when mode == "true" (case-insensitive)
+    then: <sql node>
+
+  - when: format                      # value map: different SQL per value
+    match:
+      species: <sql node>             # ?format=species
+      recording: <sql node>           # ?format=recording
+      _truthy: <sql node>             # any other truthy value
+      _default: <sql node>            # any present value not matched above
+
+  - when: [count, recording]          # list: fires when ALL are truthy (AND)
+    then: <sql node>
+
+  - when: [count, something_else]     # list + positional case list
+    match:
+      - values: [_any, x]             # something_else == x, count anything
+        then: <sql node>
+      - values: [_truthy, _absent]    # count truthy AND something_else not passed
+        then: <sql node>
+      - default: <sql node>
+
+  - else: <sql node>                  # default (a trailing bare string works too)
+```
+
+Nesting works because a payload can itself be a rule list:
+
+```yaml
+sql:
+  - when: some_value
+    match:
+      '4':
+        - when: count
+          then: <sql for value 4 with count>
+        - else: <sql for value 4>
+      _default: <sql for other values>
+  - else: <base sql>
+```
+
+### Value specs
+
+| spec | matches when the param… |
+|---|---|
+| `'literal'` (`'4'`, `'true'`) | is present and equals it (case-insensitive) |
+| `_truthy` / `_falsy` | present, and value is / isn't in `{"", "0", "false", "no", "off", "null", "none"}` |
+| `_present` / `_absent` | exists / does not exist |
+| `_any` | wildcard — present or absent (used for a position in a case list) |
+| `_default` | catch-all for any *present* value (value maps only) |
+
+In a single-param `match:` map, precedence is order-independent: exact literal > `_falsy`/`_truthy` > `_present`/`_absent` > `_default`. In a positional case list, cases match strictly top-to-bottom.
+
+### No match → URL error
+
+If no rule matches and there is no default (`else`, a trailing bare string, or a `_default`/`default` catch-all), the request returns a **400** with `{"error": "No matching query configuration for the given parameters", "http_status": 400}`. Customize it with a terminal `no_match` rule:
+
+```yaml
+sql:
+  - when: recording
+    then: SELECT [[detections]].* FROM [[detections]] WHERE recording_id = {{recording}}
+  - no_match:
+      error: "recording is required, or pass count=true for a histogram"
+      http_status: 400
+```
+
+Cookies participate via the `cookies.<name>` key (e.g. `when: cookies.role`, `equals: admin`).
+
+---
+
 # CLI
 
 ## Commands

{api_dock-0.7.0 → api_dock-0.7.1}/api_dock/database_config.py

@@ -295,6 +295,10 @@ def validate_route_config(route_config: Dict[str, Any]) -> bool:
     if 'route' not in route_config:
         return False
 
+    # The sql selector may be a plain string or a list of selector rules.
+    if 'sql' in route_config and not isinstance(route_config['sql'], (str, list)):
+        return False
+
     # Validate query_params structure if present
     if 'query_params' in route_config:
         query_params = route_config['query_params']

{api_dock-0.7.0 → api_dock-0.7.1}/api_dock/example_api_dock_config/databases/example_db.yaml

@@ -80,3 +80,17 @@ routes:
 # - debug:
 #     response:
 #       message: "Debug mode — no query executed"
+
+# Conditional SQL selection — pick a different base query from a param's
+# presence/value. Here ?count=<truthy> returns a histogram; otherwise rows.
+# The selected base still composes with query_params (WHERE + sql_append).
+# - route: detections
+#   sql:
+#     - when: count
+#       then:
+#         sql: SELECT [[items]].category, COUNT(*) AS count FROM [[items]]
+#         sql_append: GROUP BY [[items]].category
+#     - else: SELECT [[items]].* FROM [[items]]
+#   query_params:
+#     - category:
+#         sql: "[[items]].category = '{{category}}'"

{api_dock-0.7.0 → api_dock-0.7.1}/api_dock/route_mapper.py

@@ -18,7 +18,7 @@ from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
 from api_dock.auth import validate_authentication
 from api_dock.config import filter_cookies_by_config, filter_remote_query_params, find_remote_config, find_route_mapping, get_authentication_config, get_database_names, get_remote_names, get_remote_versions, get_settings, is_route_allowed, is_versioned_remote, load_main_config, merge_inherited_config, resolve_latest_version
 from api_dock.database_config import find_database_route, get_database_versions, is_versioned_database, load_database_config, merge_query_params, resolve_latest_database_version
-from api_dock.sql_builder import build_sql_query, extract_path_parameters, process_query_parameters
+from api_dock.sql_builder import build_sql_query, extract_path_parameters, process_query_parameters, SqlSelectionError
 from api_dock.storage_auth import detect_required_backends, extract_table_metadata_by_backend, extract_table_uris, setup_storage_authentication
 from api_dock.types import PreparedRequest, ProxyResponse
 
@@ -435,6 +435,13 @@ class RouteMapper:
                 route_config, database_config, path_params, query_params,
                 filtered_cookies, multi_query_params
             )
+        except SqlSelectionError as e:
+            return ProxyResponse(
+                status_code=e.status_code,
+                content=json.dumps(e.response).encode(),
+                content_type="application/json",
+                error_message=str(e.response.get("error")) if e.response.get("error") else None,
+            )
         except ValueError:
             return _error_response(500, "SQL query error")
 

{api_dock-0.7.0 → api_dock-0.7.1}/api_dock/sql_builder.py

@@ -17,9 +17,52 @@ from typing import Any, Dict, List, Optional, Tuple
 from api_dock.database_config import get_named_query, get_table_definition
 
 
+#
+# CONSTANTS
+#
+# Query-param values treated as "falsy" for _truthy/_falsy matching in the sql
+# selector. Comparison is case-insensitive after stripping surrounding space.
+FALSY_VALUES: frozenset = frozenset({"", "0", "false", "no", "off", "null", "none"})
+
+# Response returned when an sql selector matches no branch and defines no
+# default (else / trailing string / _default) or no_match override.
+DEFAULT_NO_MATCH_RESPONSE: Dict[str, Any] = {
+    "error": "No matching query configuration for the given parameters",
+    "http_status": 400,
+}
+
+# Sentinel signalling that a selector rule did not fire (distinct from a rule
+# that fires but resolves to an empty base SQL).
+_NO_MATCH: Any = object()
+
+
 #
 # PUBLIC
 #
+class SqlSelectionError(Exception):
+    """Raised when an sql selector matches no branch and defines no default.
+
+    Carries the JSON response body and HTTP status to return to the client, so
+    the caller can surface a proper URL error (default 400) rather than a
+    generic 500.
+
+    Attributes:
+        response: JSON-serializable response body to return to the client.
+        status_code: HTTP status code to return.
+    """
+
+    def __init__(self, response: Dict[str, Any]) -> None:
+        """Initialize the error from a response spec.
+
+        Args:
+            response: Response body dict; its ``http_status`` (default 400)
+                becomes the HTTP status code.
+        """
+        self.response = response
+        self.status_code = int(response.get("http_status", 400))
+        super().__init__(str(response.get("error", "No matching query configuration")))
+
+
 def build_sql_query(
         route_config: Dict[str, Any],
         database_config: Dict[str, Any],
@@ -55,8 +98,13 @@ def build_sql_query(
     if multi_query_params is None:
         multi_query_params = {}
 
-    # Get the base SQL template from route config
-    sql_template = route_config.get('sql', '')
+    # Resolve the base SQL via the selector. ``sql`` may be a plain string or a
+    # rule-list decision tree; selection is driven by path, query, and cookie
+    # params. branch_appends are post-WHERE clauses (e.g. GROUP BY) contributed
+    # by the selected branch, applied before route-level sql_append fragments.
+    selection_params = {**path_params, **query_params}
+    selection_params.update({f"cookies.{key}": value for key, value in cookies.items()})
+    sql_template, branch_appends = resolve_route_sql(route_config, selection_params)
 
     # Check if sql_template is a reference to a named query
     if sql_template.startswith("[[") and sql_template.endswith("]]"):
@@ -98,6 +146,16 @@ def build_sql_query(
             where_clause = ' WHERE ' + ' AND '.join(where_fragments)
         sql_with_tables += where_clause
 
+    # Apply post-WHERE clauses from the selected sql branch (e.g. GROUP BY for a
+    # histogram mode). Branch appends come before route-level sql_append so a
+    # branch GROUP BY precedes a shared ORDER BY / LIMIT.
+    if branch_appends:
+        expanded_branch = [
+            _substitute_table_references(fragment, database_config)
+            for fragment in branch_appends
+        ]
+        sql_with_tables += ' ' + ' '.join(expanded_branch)
+
     # Build post-WHERE append fragments (ORDER BY, LIMIT, etc.)
     append_fragments = build_append_clause_from_params(route_config, query_params, path_params)
     # Expand [[table_name]] references in APPEND fragments (same syntax as main sql)
@@ -112,6 +170,46 @@ def build_sql_query(
     return sql_with_params
 
 
+def resolve_route_sql(
+        route_config: Dict[str, Any],
+        selection_params: Dict[str, str]) -> Tuple[str, List[str]]:
+    """Resolve a route's ``sql`` selector to a base SQL string and append clauses.
+
+    The ``sql`` value may be a plain string (used directly) or a list of rules
+    forming a first-match-wins decision tree. Each rule selects an sql node based
+    on the presence and value of params. An sql node is itself a string, a leaf
+    object (``{sql, sql_append}``), or a nested rule list.
+
+    Rule forms (evaluated top-to-bottom, first match wins):
+      - ``{when: <param>, then: <node>}`` — fires when the param is truthy.
+      - ``{when: <param>, equals: <valspec>, then: <node>}`` — fires on a value.
+      - ``{when: <param>, match: {<valspec>: <node>, ...}}`` — value map.
+      - ``{when: [<params>], then: <node>}`` — fires when all params are truthy.
+      - ``{when: [<params>], match: [{values: [...], then: <node>}, ...]}``
+      - ``{else: <node>}`` or a trailing bare string — the default.
+      - ``{no_match: <response>}`` — raise a URL error instead of a default.
+
+    Args:
+        route_config: Route configuration dictionary. ``sql`` is a string or a
+            list of selector rules.
+        selection_params: Merged params available for matching, keyed by name
+            (path and query params, plus cookies as ``cookies.<name>``). A key
+            is "present" iff it appears here.
+
+    Returns:
+        Tuple of ``(base_sql, branch_appends)`` where ``branch_appends`` are
+        post-WHERE SQL fragments contributed by the selected branch.
+
+    Raises:
+        SqlSelectionError: If no branch matches and no default/no_match is given.
+    """
+    sql_spec = route_config.get('sql', '')
+    resolved = _resolve_sql_node(sql_spec, selection_params)
+    if resolved is None:
+        raise SqlSelectionError(dict(DEFAULT_NO_MATCH_RESPONSE))
+    return resolved
+
+
 # Keep backward compatibility with old signature
 def build_sql_query_legacy(
         sql_template: str,
@@ -705,4 +803,293 @@ def _substitute_variables_in_dict(template_dict: Dict[str, Any], params: Dict[st
             result[key] = [_substitute_variables_in_string(str(item), params) if isinstance(item, str) else item for item in value]
         else:
             result[key] = value
-    return result
+    return result
+
+
+def _resolve_sql_node(node: Any, params: Dict[str, str]) -> Optional[Tuple[str, List[str]]]:
+    """Resolve an sql node to a base SQL string and post-WHERE append fragments.
+
+    An sql node is a string (base SQL, no appends), a leaf object
+    (``{sql, sql_append}``), or a rule list (nested selection).
+
+    Args:
+        node: The sql node to resolve.
+        params: Merged selection params (see resolve_route_sql).
+
+    Returns:
+        Tuple of (base_sql, branch_appends), or None if a rule-list node matched
+        nothing and defined no default.
+
+    Raises:
+        SqlSelectionError: If a nested no_match rule is reached.
+    """
+    if isinstance(node, str):
+        return (node, [])
+    if isinstance(node, dict):
+        if 'sql' in node:
+            return (str(node.get('sql', '')), _as_append_list(node.get('sql_append')))
+        return None
+    if isinstance(node, list):
+        return _resolve_rule_list(node, params)
+    return None
+
+
+def _resolve_rule_list(rules: List[Any], params: Dict[str, str]) -> Optional[Tuple[str, List[str]]]:
+    """Resolve a rule list, returning the first matching branch's node.
+
+    Args:
+        rules: List of selector rules (see resolve_route_sql).
+        params: Merged selection params.
+
+    Returns:
+        Tuple of (base_sql, branch_appends), or None if nothing matched.
+
+    Raises:
+        SqlSelectionError: If a no_match rule is reached before any match.
+    """
+    for item in rules:
+        # Terminal bare-string default.
+        if isinstance(item, str):
+            return (item, [])
+        if not isinstance(item, dict):
+            continue
+        if 'else' in item:
+            return _require_node(item['else'], params)
+        if 'no_match' in item:
+            raise SqlSelectionError(_no_match_response(item['no_match']))
+        if 'when' in item:
+            matched = _match_rule(item, params)
+            if matched is _NO_MATCH:
+                continue
+            return _require_node(matched, params)
+    return None
+
+
+def _require_node(node: Any, params: Dict[str, str]) -> Tuple[str, List[str]]:
+    """Resolve an sql node that must yield a result (committed branch).
+
+    Args:
+        node: The sql node to resolve.
+        params: Merged selection params.
+
+    Returns:
+        Tuple of (base_sql, branch_appends).
+
+    Raises:
+        SqlSelectionError: If the node resolves to no match (e.g. a nested rule
+            list with no default).
+    """
+    resolved = _resolve_sql_node(node, params)
+    if resolved is None:
+        raise SqlSelectionError(dict(DEFAULT_NO_MATCH_RESPONSE))
+    return resolved
+
+
+def _match_rule(rule: Dict[str, Any], params: Dict[str, str]) -> Any:
+    """Evaluate a ``when`` rule, returning its payload node or _NO_MATCH.
+
+    Args:
+        rule: A rule dict containing ``when`` plus optional equals/match/then.
+        params: Merged selection params.
+
+    Returns:
+        The selected sql node to resolve, or _NO_MATCH if the rule did not fire.
+    """
+    when = rule.get('when')
+    if isinstance(when, list):
+        return _match_multi(rule, [str(w) for w in when], params)
+    return _match_single(rule, str(when), params)
+
+
+def _match_single(rule: Dict[str, Any], param: str, params: Dict[str, str]) -> Any:
+    """Evaluate a single-param ``when`` rule.
+
+    Args:
+        rule: The rule dict.
+        param: The single param name from ``when``.
+        params: Merged selection params.
+
+    Returns:
+        The selected sql node, or _NO_MATCH.
+    """
+    present = param in params
+    value = params.get(param)
+    if 'match' in rule:
+        node = _resolve_value_map(rule['match'], value, present)
+        return node if node is not None else _NO_MATCH
+    spec = rule.get('equals', '_truthy')
+    if _value_matches(spec, value, present):
+        return rule.get('then', '')
+    return _NO_MATCH
+
+
+def _match_multi(rule: Dict[str, Any], param_names: List[str], params: Dict[str, str]) -> Any:
+    """Evaluate a multi-param (list ``when``) rule.
+
+    ``match`` is a positional case list; otherwise the rule fires when every
+    named param satisfies ``equals`` (positional) or, by default, is truthy.
+
+    Args:
+        rule: The rule dict.
+        param_names: The param names from ``when``.
+        params: Merged selection params.
+
+    Returns:
+        The selected sql node, or _NO_MATCH.
+    """
+    if 'match' in rule:
+        cases = rule['match']
+        if not isinstance(cases, list):
+            return _NO_MATCH
+        for case in cases:
+            if not isinstance(case, dict):
+                continue
+            if 'default' in case:
+                return case['default']
+            values = case.get('values')
+            if not isinstance(values, list) or len(values) != len(param_names):
+                continue
+            if _all_positions_match(param_names, values, params):
+                return case.get('then', '')
+        return _NO_MATCH
+
+    specs = rule.get('equals')
+    if isinstance(specs, list) and len(specs) == len(param_names):
+        if _all_positions_match(param_names, specs, params):
+            return rule.get('then', '')
+        return _NO_MATCH
+
+    # Default: fire only when every named param is truthy (AND).
+    for name in param_names:
+        if not _value_matches('_truthy', params.get(name), name in params):
+            return _NO_MATCH
+    return rule.get('then', '')
+
+
+def _all_positions_match(param_names: List[str], specs: List[Any], params: Dict[str, str]) -> bool:
+    """Check that each param satisfies its positional value spec.
+
+    Args:
+        param_names: Param names, aligned with ``specs``.
+        specs: Value specs, one per param.
+        params: Merged selection params.
+
+    Returns:
+        True if every position matches, False otherwise.
+    """
+    for name, spec in zip(param_names, specs):
+        if not _value_matches(spec, params.get(name), name in params):
+            return False
+    return True
+
+
+def _resolve_value_map(value_map: Any, value: Optional[str], present: bool) -> Any:
+    """Select an sql node from a single-param value map by precedence.
+
+    Precedence (order-independent): exact literal > _falsy/_truthy >
+    _present/_absent > _default. An absent param matches only _absent.
+
+    Args:
+        value_map: Mapping of value spec -> sql node.
+        value: The param's value (or None if absent).
+        present: Whether the param is present.
+
+    Returns:
+        The matching sql node, or None if nothing matched.
+    """
+    if not isinstance(value_map, dict):
+        return None
+
+    if not present:
+        return value_map.get('_absent')
+
+    value_norm = str(value).strip().lower()
+    # 1. Exact literal (case-insensitive) among non-special keys.
+    for key, node in value_map.items():
+        if str(key).startswith('_'):
+            continue
+        if str(key).strip().lower() == value_norm:
+            return node
+    # 2. Truthiness.
+    if _is_truthy(value):
+        if '_truthy' in value_map:
+            return value_map['_truthy']
+    elif '_falsy' in value_map:
+        return value_map['_falsy']
+    # 3. Presence.
+    if '_present' in value_map:
+        return value_map['_present']
+    # 4. Catch-all.
+    return value_map.get('_default')
+
+
+def _value_matches(spec: Any, value: Optional[str], present: bool) -> bool:
+    """Check whether a param value satisfies a single value spec.
+
+    Args:
+        spec: A literal string or special token (_any, _present, _absent,
+            _truthy, _falsy, _default).
+        value: The param's value (or None if absent).
+        present: Whether the param is present.
+
+    Returns:
+        True if the value satisfies the spec, False otherwise.
+    """
+    spec_str = str(spec)
+    if spec_str in ('_any', '_default'):
+        return True
+    if spec_str == '_present':
+        return present
+    if spec_str == '_absent':
+        return not present
+    if spec_str == '_truthy':
+        return present and _is_truthy(value)
+    if spec_str == '_falsy':
+        return present and not _is_truthy(value)
+    return present and str(value).strip().lower() == spec_str.strip().lower()
+
+
+def _is_truthy(value: Optional[str]) -> bool:
+    """Return whether a param value is "truthy" per FALSY_VALUES.
+
+    Args:
+        value: The value to test.
+
+    Returns:
+        True unless the normalized value is in FALSY_VALUES.
+    """
+    return str(value).strip().lower() not in FALSY_VALUES
+
+
+def _as_append_list(value: Any) -> List[str]:
+    """Normalize a leaf node's sql_append into a list of clause strings.
+
+    Args:
+        value: A string, list of strings, or None.
+
+    Returns:
+        List of append clause strings (empty if value is None/unsupported).
+    """
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    return []
+
+
+def _no_match_response(spec: Any) -> Dict[str, Any]:
+    """Build a no_match response body, defaulting http_status to 400.
+
+    Args:
+        spec: A response dict or a plain error string/value.
+
+    Returns:
+        Response body dict with an http_status key.
+    """
+    if isinstance(spec, dict):
+        response = dict(spec)
+        response.setdefault('http_status', 400)
+        return response
+    return {'error': str(spec), 'http_status': 400}

{api_dock-0.7.0 → api_dock-0.7.1}/api_dock.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api_dock
-Version: 0.7.0
+Version: 0.7.1
 Summary: A flexible API gateway that allows you to proxy requests to multiple remote APIs and Databases
 Author-email: Brookie Guzder-Williams <bguzder-williams@berkeley.edu>
 License-Expression: BSD-3-Clause
@@ -672,6 +672,125 @@ Parameters are processed in this order (first match wins for early returns):
 
 ---
 
+## Conditional SQL Selection
+
+Some routes need a *different* base query depending on the request — for example, `?count=true` should return a species histogram (`SELECT … COUNT(*) … GROUP BY …`) rather than rows. `sql_append` can't help (it only adds trailing clauses), and a second `route:` can't either (the path is identical). For this, a route's `sql` may be a **rule list** instead of a string: a first-match-wins decision tree that picks the base query from the presence and value of path, query, and cookie params.
+
+Everything downstream is unchanged: the selected base composes with `query_params` WHERE-fragments and `sql_append` exactly as a plain `sql:` string does.
+
+### The histogram example
+
+```yaml
+routes:
+  - route: detections
+    sql:
+      # ?count=<truthy>  → species histogram
+      - when: count
+        then:
+          sql: >
+            SELECT [[detections]].common_name, [[detections]].scientific_name,
+                   COUNT(*) AS count
+            FROM [[detections]]
+          sql_append: GROUP BY [[detections]].common_name, [[detections]].scientific_name
+      # otherwise → detection rows
+      - else: SELECT [[detections]].* FROM [[detections]]
+    query_params:
+      - recording:
+          sql: "[[detections]].recording_id = {{recording}}"
+          multivalue_sql: "[[detections]].recording_id IN {{recording}}"
+      - limit:
+          sql_append: LIMIT {{limit}}          # applies in BOTH modes
+```
+
+```bash
+GET /db/detections?recording=1&count=true
+# SELECT detections.common_name, detections.scientific_name, COUNT(*) AS count
+#   FROM detections WHERE detections.recording_id = '1'
+#   GROUP BY detections.common_name, detections.scientific_name
+
+GET /db/detections?recording=1
+# SELECT detections.* FROM detections WHERE detections.recording_id = '1'
+```
+
+Note the pipeline order: the selected branch's `sql_append` (the `GROUP BY`) is applied **before** route-level `sql_append` (the shared `LIMIT`), so SQL clause order stays valid.
+
+### Rule forms
+
+A `sql` list contains rules evaluated top to bottom; the **first match wins**. Each rule's payload (an *sql node*) is a SQL string, a leaf object `{sql, sql_append}`, or a nested rule list.
+
+```yaml
+sql:
+  - when: count                       # fires when `count` is truthy (shorthand for equals: _truthy)
+    then: <sql node>
+
+  - when: mode
+    equals: 'true'                    # fires only when mode == "true" (case-insensitive)
+    then: <sql node>
+
+  - when: format                      # value map: different SQL per value
+    match:
+      species: <sql node>             # ?format=species
+      recording: <sql node>           # ?format=recording
+      _truthy: <sql node>             # any other truthy value
+      _default: <sql node>            # any present value not matched above
+
+  - when: [count, recording]          # list: fires when ALL are truthy (AND)
+    then: <sql node>
+
+  - when: [count, something_else]     # list + positional case list
+    match:
+      - values: [_any, x]             # something_else == x, count anything
+        then: <sql node>
+      - values: [_truthy, _absent]    # count truthy AND something_else not passed
+        then: <sql node>
+      - default: <sql node>
+
+  - else: <sql node>                  # default (a trailing bare string works too)
+```
+
+Nesting works because a payload can itself be a rule list:
+
+```yaml
+sql:
+  - when: some_value
+    match:
+      '4':
+        - when: count
+          then: <sql for value 4 with count>
+        - else: <sql for value 4>
+      _default: <sql for other values>
+  - else: <base sql>
+```
+
+### Value specs
+
+| spec | matches when the param… |
+|---|---|
+| `'literal'` (`'4'`, `'true'`) | is present and equals it (case-insensitive) |
+| `_truthy` / `_falsy` | present, and value is / isn't in `{"", "0", "false", "no", "off", "null", "none"}` |
+| `_present` / `_absent` | exists / does not exist |
+| `_any` | wildcard — present or absent (used for a position in a case list) |
+| `_default` | catch-all for any *present* value (value maps only) |
+
+In a single-param `match:` map, precedence is order-independent: exact literal > `_falsy`/`_truthy` > `_present`/`_absent` > `_default`. In a positional case list, cases match strictly top-to-bottom.
+
+### No match → URL error
+
+If no rule matches and there is no default (`else`, a trailing bare string, or a `_default`/`default` catch-all), the request returns a **400** with `{"error": "No matching query configuration for the given parameters", "http_status": 400}`. Customize it with a terminal `no_match` rule:
+
+```yaml
+sql:
+  - when: recording
+    then: SELECT [[detections]].* FROM [[detections]] WHERE recording_id = {{recording}}
+  - no_match:
+      error: "recording is required, or pass count=true for a histogram"
+      http_status: 400
+```
+
+Cookies participate via the `cookies.<name>` key (e.g. `when: cookies.role`, `equals: admin`).
+
+---
+
 # CLI
 
 ## Commands

{api_dock-0.7.0 → api_dock-0.7.1}/api_dock.egg-info/SOURCES.txt

@@ -27,4 +27,5 @@ api_dock/example_api_dock_config/remotes/example_remote.yaml
 tests/test_inject_cookies.py
 tests/test_proxy_pipeline.py
 tests/test_sql_builder.py
+tests/test_sql_selector.py
 tests/test_types.py

{api_dock-0.7.0 → api_dock-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "api_dock"
-version = "0.7.0"
+version = "0.7.1"
 description = "A flexible API gateway that allows you to proxy requests to multiple remote APIs and Databases"
 readme = "README.md"
 license = "BSD-3-Clause"

api_dock-0.7.1/tests/test_sql_selector.py

@@ -0,0 +1,277 @@
+"""
+
+Tests for the conditional SQL selector in the SQL builder.
+
+Covers ``resolve_route_sql`` (the decision-tree resolver) and its end-to-end
+composition with the existing query_params WHERE/append pipeline in
+``build_sql_query``, plus the SqlSelectionError path through
+``RouteMapper.map_database_route``.
+
+The selector lets a route's ``sql`` be a plain string (today's behavior) or a
+first-match-wins list of rules that pick a base SQL node from the presence and
+value of path/query/cookie params.
+
+License: BSD 3-Clause
+
+"""
+
+#
+# IMPORTS
+#
+import json
+from unittest.mock import patch
+
+import pytest
+
+from api_dock.route_mapper import RouteMapper
+from api_dock.sql_builder import build_sql_query, resolve_route_sql, SqlSelectionError
+
+
+#
+# CONSTANTS
+#
+DATABASE_CONFIG = {"tables": {"detections": "data/detections.parquet"}}
+
+COUNT_ROUTE = {
+    "route": "detections",
+    "sql": [
+        {
+            "when": "count",
+            "then": {
+                "sql": (
+                    "SELECT [[detections]].common_name, [[detections]].scientific_name, "
+                    "COUNT(*) AS count FROM [[detections]]"
+                ),
+                "sql_append": (
+                    "GROUP BY [[detections]].common_name, [[detections]].scientific_name"
+                ),
+            },
+        },
+        {"else": "SELECT [[detections]].* FROM [[detections]]"},
+    ],
+    "query_params": [
+        {
+            "recording": {
+                "sql": "[[detections]].recording_id = {{recording}}",
+                "multivalue_sql": "[[detections]].recording_id IN {{recording}}",
+            }
+        },
+        {"limit": {"sql_append": "LIMIT {{limit}}"}},
+    ],
+}
+
+
+#
+# PUBLIC
+#
+class TestResolveRouteSql:
+    """Unit tests for the decision-tree resolver."""
+
+    def test_plain_string_passthrough(self) -> None:
+        """A plain string sql resolves to itself with no branch appends."""
+        assert resolve_route_sql({"sql": "SELECT 1"}, {}) == ("SELECT 1", [])
+
+    def test_missing_sql_returns_empty(self) -> None:
+        """A route with no sql resolves to an empty base (legacy behavior)."""
+        assert resolve_route_sql({}, {}) == ("", [])
+
+    def test_when_truthy_fires(self) -> None:
+        """A bare when fires on a truthy value."""
+        rc = {"sql": [{"when": "count", "then": "HIST"}, {"else": "BASE"}]}
+        assert resolve_route_sql(rc, {"count": "True"}) == ("HIST", [])
+
+    def test_when_absent_falls_to_else(self) -> None:
+        """An absent query param skips the rule and falls to else."""
+        rc = {"sql": [{"when": "count", "then": "HIST"}, {"else": "BASE"}]}
+        assert resolve_route_sql(rc, {}) == ("BASE", [])
+
+    def test_when_falsy_falls_to_else(self) -> None:
+        """A falsy value does not fire a bare when."""
+        rc = {"sql": [{"when": "count", "then": "HIST"}, {"else": "BASE"}]}
+        assert resolve_route_sql(rc, {"count": "false"}) == ("BASE", [])
+
+    def test_leaf_object_with_append(self) -> None:
+        """A leaf object contributes base sql plus post-WHERE append clauses."""
+        rc = {
+            "sql": [
+                {"when": "count", "then": {"sql": "HIST", "sql_append": "GROUP BY x"}},
+                "BASE",
+            ]
+        }
+        assert resolve_route_sql(rc, {"count": "1"}) == ("HIST", ["GROUP BY x"])
+
+    def test_trailing_string_default(self) -> None:
+        """A trailing bare string acts as the default (implicit else)."""
+        rc = {"sql": [{"when": "count", "then": "HIST"}, "BASE"]}
+        assert resolve_route_sql(rc, {}) == ("BASE", [])
+
+    def test_equals_literal_case_insensitive(self) -> None:
+        """equals matches a specific value, case-insensitively, and only that value."""
+        rc = {"sql": [{"when": "mode", "equals": "true", "then": "T"}, {"else": "E"}]}
+        assert resolve_route_sql(rc, {"mode": "True"}) == ("T", [])
+        assert resolve_route_sql(rc, {"mode": "1"}) == ("E", [])
+
+    def test_value_map_precedence_literal_over_truthy(self) -> None:
+        """A value map prefers an exact literal over _truthy regardless of order."""
+        rc = {"sql": [{"when": "count", "match": {"_truthy": "TRU", "true": "LIT"}}, {"else": "E"}]}
+        assert resolve_route_sql(rc, {"count": "true"}) == ("LIT", [])
+        assert resolve_route_sql(rc, {"count": "1"}) == ("TRU", [])
+
+    def test_value_map_default_requires_presence(self) -> None:
+        """_default fires for any present value but not when the param is absent."""
+        rc = {"sql": [{"when": "count", "match": {"_default": "D"}}, {"else": "E"}]}
+        assert resolve_route_sql(rc, {"count": "anything"}) == ("D", [])
+        assert resolve_route_sql(rc, {}) == ("E", [])
+
+    def test_value_map_absent(self) -> None:
+        """_absent fires only when the param is absent."""
+        rc = {"sql": [{"when": "count", "match": {"_absent": "A", "_truthy": "T"}}, {"else": "E"}]}
+        assert resolve_route_sql(rc, {}) == ("A", [])
+        assert resolve_route_sql(rc, {"count": "1"}) == ("T", [])
+
+    def test_value_map_falsy(self) -> None:
+        """_falsy fires when a present value is falsy."""
+        rc = {"sql": [{"when": "flag", "match": {"_falsy": "F", "_truthy": "T"}}, {"else": "E"}]}
+        assert resolve_route_sql(rc, {"flag": "0"}) == ("F", [])
+        assert resolve_route_sql(rc, {"flag": "yes"}) == ("T", [])
+
+    def test_multi_when_all_truthy(self) -> None:
+        """A list when with then fires only when every param is truthy (AND)."""
+        rc = {"sql": [{"when": ["a", "b"], "then": "BOTH"}, {"else": "E"}]}
+        assert resolve_route_sql(rc, {"a": "1", "b": "1"}) == ("BOTH", [])
+        assert resolve_route_sql(rc, {"a": "1"}) == ("E", [])
+
+    def test_multi_match_case_list_with_any(self) -> None:
+        """A positional case list matches top-to-bottom, honoring _any wildcards."""
+        rc = {
+            "sql": [
+                {
+                    "when": ["count", "something"],
+                    "match": [
+                        {"values": ["_any", "x"], "then": "SX"},
+                        {"values": ["_truthy", "_absent"], "then": "CT"},
+                        {"default": "DEF"},
+                    ],
+                },
+                {"else": "E"},
+            ]
+        }
+        assert resolve_route_sql(rc, {"something": "x"}) == ("SX", [])
+        assert resolve_route_sql(rc, {"count": "1"}) == ("CT", [])
+        assert resolve_route_sql(rc, {"count": "1", "something": "y"}) == ("DEF", [])
+
+    def test_nested_rule_list(self) -> None:
+        """A branch payload may itself be a nested rule list."""
+        rc = {
+            "sql": [
+                {
+                    "when": "some_value",
+                    "match": {
+                        "4": [{"when": "count", "then": "FOUR_COUNT"}, {"else": "FOUR"}],
+                        "_default": "OTHER",
+                    },
+                },
+                {"else": "E"},
+            ]
+        }
+        assert resolve_route_sql(rc, {"some_value": "4", "count": "1"}) == ("FOUR_COUNT", [])
+        assert resolve_route_sql(rc, {"some_value": "4"}) == ("FOUR", [])
+        assert resolve_route_sql(rc, {"some_value": "9"}) == ("OTHER", [])
+
+    def test_cookie_param_selection(self) -> None:
+        """Cookies participate in selection via the cookies.<name> key."""
+        rc = {"sql": [{"when": "cookies.role", "equals": "admin", "then": "A"}, {"else": "E"}]}
+        assert resolve_route_sql(rc, {"cookies.role": "admin"}) == ("A", [])
+        assert resolve_route_sql(rc, {"cookies.role": "user"}) == ("E", [])
+
+    def test_no_match_raises_default_400(self) -> None:
+        """No branch and no default raises a 400 SqlSelectionError."""
+        rc = {"sql": [{"when": "count", "then": "HIST"}]}
+        with pytest.raises(SqlSelectionError) as exc:
+            resolve_route_sql(rc, {})
+        assert exc.value.status_code == 400
+        assert "error" in exc.value.response
+
+    def test_no_match_custom_response(self) -> None:
+        """A no_match rule provides a custom error body and status."""
+        rc = {
+            "sql": [
+                {"when": "recording", "then": "R"},
+                {"no_match": {"error": "recording required", "http_status": 422}},
+            ]
+        }
+        with pytest.raises(SqlSelectionError) as exc:
+            resolve_route_sql(rc, {})
+        assert exc.value.status_code == 422
+        assert exc.value.response["error"] == "recording required"
+
+
+class TestSelectorComposition:
+    """End-to-end SQL assembly combining the selector with query_params."""
+
+    def test_count_mode_composes_where_and_group_by(self) -> None:
+        """count=True selects the histogram base; recording filter + GROUP BY compose."""
+        sql = build_sql_query(
+            COUNT_ROUTE, DATABASE_CONFIG, {}, {"recording": "1", "count": "True"}, {}, {}
+        )
+        expected = (
+            "SELECT detections.common_name, detections.scientific_name, COUNT(*) AS count "
+            "FROM 'data/detections.parquet' AS detections "
+            "WHERE detections.recording_id = '1' "
+            "GROUP BY detections.common_name, detections.scientific_name"
+        )
+        assert sql == expected
+
+    def test_count_mode_with_shared_limit(self) -> None:
+        """A shared LIMIT append lands after the branch GROUP BY."""
+        sql = build_sql_query(
+            COUNT_ROUTE, DATABASE_CONFIG, {},
+            {"recording": "1", "count": "1", "limit": "20"}, {}, {}
+        )
+        assert sql.endswith("GROUP BY detections.common_name, detections.scientific_name LIMIT 20")
+
+    def test_default_mode_returns_rows(self) -> None:
+        """Without count, the else branch returns rows with the recording filter."""
+        sql = build_sql_query(COUNT_ROUTE, DATABASE_CONFIG, {}, {"recording": "1"}, {}, {})
+        expected = (
+            "SELECT detections.* FROM 'data/detections.parquet' AS detections "
+            "WHERE detections.recording_id = '1'"
+        )
+        assert sql == expected
+
+    def test_no_match_raises_through_build(self) -> None:
+        """A selector with no default raises SqlSelectionError from build_sql_query."""
+        route = {"route": "detections", "sql": [{"when": "count", "then": "SELECT 1"}]}
+        with pytest.raises(SqlSelectionError):
+            build_sql_query(route, DATABASE_CONFIG, {}, {}, {}, {})
+
+
+class TestMapDatabaseRouteSelection:
+    """The SqlSelectionError path surfaces as a proper URL error response."""
+
+    def _make_rm(self):
+        rm = RouteMapper.__new__(RouteMapper)
+        rm.remote_names = []
+        rm.database_names = ["mydb"]
+        rm.config = {}
+        rm.settings = {}
+        return rm
+
+    @pytest.mark.anyio
+    async def test_selection_error_returns_400(self) -> None:
+        """No matching branch (and no default) yields a 400 with an error body."""
+        rm = self._make_rm()
+        route = {"route": "detections", "sql": [{"when": "count", "then": "SELECT 1"}]}
+        db_cfg = {"tables": {}, "routes": [route]}
+        with patch("api_dock.route_mapper.is_versioned_database", return_value=False), \
+             patch("api_dock.route_mapper.load_database_config", return_value=db_cfg), \
+             patch("api_dock.route_mapper.merge_inherited_config", side_effect=lambda c, p: c), \
+             patch("api_dock.route_mapper.filter_cookies_by_config", return_value={}), \
+             patch("api_dock.route_mapper.get_authentication_config", return_value=None), \
+             patch("api_dock.route_mapper.find_database_route", return_value=route), \
+             patch("api_dock.route_mapper.merge_query_params", side_effect=lambda r, d: r):
+            result = await rm.map_database_route("mydb", "detections", {}, {})
+
+        assert result.status_code == 400
+        parsed = json.loads(result.content)
+        assert "error" in parsed