api-dock 0.5.0__tar.gz → 0.6.0__tar.gz

{api_dock-0.5.0 → api_dock-0.6.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: api_dock
-Version: 0.5.0
+Version: 0.6.0
 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: BSd 3-clause
+License-Expression: BSD-3-Clause
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -26,7 +26,7 @@ Requires-Dist: pyyaml<7,>=6.0.3
 Requires-Dist: httpx<0.29,>=0.28.1
 Requires-Dist: duckdb<2,>=1.1.3
 Requires-Dist: flask
-Requires-Dist: cryptography<47,>=46.0.5
+Requires-Dist: cryptography<49.0.0,>=48.0.0
 Requires-Dist: boto3<2,>=1.42.59
 Provides-Extra: dev
 Requires-Dist: pycodestyle<3,>=2.14.0; extra == "dev"
@@ -349,7 +349,7 @@ For now only parquet support is working but we will be adding other Databases in
 
 ### Database Configuration
 
-Database configurations are stored in `config/databases/` directory. Each database defines:
+Database configurations are stored in `api_dock_config/databases/` directory. Each database defines:
 - **tables**: Mapping of table names to file paths (supports S3, GCS, HTTPS, local paths)
 - **queries**: Named SQL queries for reuse
 - **routes**: REST endpoints mapped to SQL queries
@@ -702,30 +702,79 @@ API Dock supports cookie extraction and authentication for both remote APIs and
 
 ## Cookie Configuration
 
-Configure cookies to extract from incoming requests and make them available as template variables:
+### Forwarding client cookies
+
+Configure which cookies to extract from incoming requests and forward to the upstream API (or make available as template variables in SQL routes):
 
 ```yaml
-# Enable all cookies (default: false)
+# Forward all cookies from the client request
 cookies: true
 
-# Or specify specific cookies to extract
+# Forward only specific cookies
 cookies: [session_id, auth_token, user_preferences]
 
-# Disable all cookies (default behavior)
+# Forward no cookies (default behavior)
 cookies: false
 ```
 
-When `cookies: true`, all cookies are accepted and available. When `cookies: false` (default), no cookies are processed except authentication cookies when authentication is configured. When providing a list, only specified cookies are extracted.
+When `cookies: true`, all cookies are accepted and available. When `cookies: false` (default), no cookies are processed except authentication cookies when authentication is configured. When providing a list, only the named cookies are forwarded.
 
-Cookies can then be accessed in SQL queries using `{{cookies.cookie_name}}`:
+Forwarded cookies are accessible in SQL queries using `{{cookies.cookie_name}}`:
 
 ```yaml
-# Database route using cookies
 routes:
   - route: user/profile
     sql: SELECT * FROM [[users]] WHERE session_id = '{{cookies.session_id}}'
 ```
 
+### Injecting cookies from the server environment
+
+The `cookies` list also accepts dict entries to inject cookies into every outgoing upstream request, regardless of what the client sent. This is useful when the upstream API requires a server-side credential (e.g. a session token stored in an environment variable) rather than a cookie from the end user.
+
+Dict entries and string entries can be mixed freely in the same list.
+
+```yaml
+cookies:
+  - session_id                            # forward this cookie from the client request
+  - key: __Secure-authjs.session-token    # inject from environment variable
+    value: "env:SOUNDHUB_SESSION_TOKEN"
+```
+
+#### Dict entry forms
+
+| Form | Behaviour |
+|---|---|
+| `{key: NAME, value: "literal"}` | Inject cookie `NAME` with the literal string `"literal"` |
+| `{key: NAME, value: "env:MY_VAR"}` | Inject cookie `NAME` with the value of env var `MY_VAR`; empty string if unset |
+| `{key: MY_VAR}` | Shorthand — equivalent to `{key: MY_VAR, value: "env:MY_VAR"}` |
+
+The shorthand form uses the key as both the cookie name **and** the env var name. Use the explicit `value: "env:..."` form when the cookie name and the env var name differ (which is common — cookie names often contain characters that aren't valid env var names).
+
+#### Example: proxying an API that requires a session cookie
+
+```yaml
+# api_dock_config/remotes/my_service/1.0.yaml
+name: my_service
+url: https://api.example.com
+
+cookies:
+  - key: __Secure-authjs.session-token
+    value: "env:MY_SERVICE_SESSION_TOKEN"
+```
+
+Set the env var before starting api-dock:
+
+```bash
+export MY_SERVICE_SESSION_TOKEN="your-session-token-here"
+pixi run api-dock start
+```
+
+Every request proxied to `my_service` will include the `__Secure-authjs.session-token` cookie, even if the client did not send one.
+
+#### Injection precedence
+
+If an injected cookie has the same name as a forwarded client cookie, the injected value takes precedence. This ensures the server-side credential is always used, regardless of what the client sends.
+
 ## Authentication Configuration
 
 Configure authentication to validate requests before processing. Multiple authentication methods are supported:
@@ -1119,6 +1168,58 @@ pixi run jupyter lab .
 pixi run python scripts/hello_world.py
 ```
 
+---
+
+---
+
+# Development
+
+## Publishing a Release
+
+```bash
+# 0. Make sure you are on `main` and merged with any changes
+
+# 1. Bump version in pyproject.toml
+
+# 2. Commit everything
+git add -A
+git commit -m "v0.6.0: proxy passthrough fixes, cookie injection"
+
+# 3. Tag and push
+git tag v0.6.0
+git push origin main v0.6.0
+
+# 4. Build the wheel (requires the `dev` pixi environment)
+rm -rf dist/
+find . -name "__pycache__" -type d -exec rm -rf {} +
+find . -name "*.pyc" -delete
+pixi run -e dev python -m build --wheel
+ls dist/*.whl
+
+# 5. Create GitHub release with the wheel attached
+gh release create v0.6.0 dist/api_dock-0.6.0-py3-none-any.whl \
+    --title "v0.6.0" --notes "$(cat <<'EOF'
+* new features
+    - Cookie injection: dict entries in the `cookies` list inject server-side cookies into upstream requests, with `env:MY_VAR` env var support and literal value support
+* bug fixes
+    - Binary responses (image, audio) no longer corrupted — raw bytes passed through with correct content-type
+    - 3xx redirects returned to client when `follow_redirects: false` (previously followed internally, doubling egress)
+    - Upstream response headers (Cache-Control, ETag, Last-Modified, etc.) now forwarded to client
+    - Upstream 4xx/5xx error bodies passed through verbatim (previously wrapped/swallowed)
+    - JSON responses no longer re-serialized — raw bytes returned as-is, preserving exact upstream payload
+* cleanup / other improvements
+    - Added `ProxyResponse` typed dataclass as the return contract for `map_route()` and `map_database_route()`
+    - Added test suite (38 tests covering proxy pipeline and cookie injection)
+    - Removed broken root `__init__.py` that caused pytest import conflicts
+    - Bumped cryptography dependency to >=48.0.0,<49.0.0
+EOF
+)"
+
+# 6. Publish to PyPI
+pixi run -e dev python -m twine upload dist/*.whl
+```
+
+
 ---
 
 # License

{api_dock-0.5.0 → api_dock-0.6.0}/README.md

@@ -310,7 +310,7 @@ For now only parquet support is working but we will be adding other Databases in
 
 ### Database Configuration
 
-Database configurations are stored in `config/databases/` directory. Each database defines:
+Database configurations are stored in `api_dock_config/databases/` directory. Each database defines:
 - **tables**: Mapping of table names to file paths (supports S3, GCS, HTTPS, local paths)
 - **queries**: Named SQL queries for reuse
 - **routes**: REST endpoints mapped to SQL queries
@@ -663,30 +663,79 @@ API Dock supports cookie extraction and authentication for both remote APIs and
 
 ## Cookie Configuration
 
-Configure cookies to extract from incoming requests and make them available as template variables:
+### Forwarding client cookies
+
+Configure which cookies to extract from incoming requests and forward to the upstream API (or make available as template variables in SQL routes):
 
 ```yaml
-# Enable all cookies (default: false)
+# Forward all cookies from the client request
 cookies: true
 
-# Or specify specific cookies to extract
+# Forward only specific cookies
 cookies: [session_id, auth_token, user_preferences]
 
-# Disable all cookies (default behavior)
+# Forward no cookies (default behavior)
 cookies: false
 ```
 
-When `cookies: true`, all cookies are accepted and available. When `cookies: false` (default), no cookies are processed except authentication cookies when authentication is configured. When providing a list, only specified cookies are extracted.
+When `cookies: true`, all cookies are accepted and available. When `cookies: false` (default), no cookies are processed except authentication cookies when authentication is configured. When providing a list, only the named cookies are forwarded.
 
-Cookies can then be accessed in SQL queries using `{{cookies.cookie_name}}`:
+Forwarded cookies are accessible in SQL queries using `{{cookies.cookie_name}}`:
 
 ```yaml
-# Database route using cookies
 routes:
   - route: user/profile
     sql: SELECT * FROM [[users]] WHERE session_id = '{{cookies.session_id}}'
 ```
 
+### Injecting cookies from the server environment
+
+The `cookies` list also accepts dict entries to inject cookies into every outgoing upstream request, regardless of what the client sent. This is useful when the upstream API requires a server-side credential (e.g. a session token stored in an environment variable) rather than a cookie from the end user.
+
+Dict entries and string entries can be mixed freely in the same list.
+
+```yaml
+cookies:
+  - session_id                            # forward this cookie from the client request
+  - key: __Secure-authjs.session-token    # inject from environment variable
+    value: "env:SOUNDHUB_SESSION_TOKEN"
+```
+
+#### Dict entry forms
+
+| Form | Behaviour |
+|---|---|
+| `{key: NAME, value: "literal"}` | Inject cookie `NAME` with the literal string `"literal"` |
+| `{key: NAME, value: "env:MY_VAR"}` | Inject cookie `NAME` with the value of env var `MY_VAR`; empty string if unset |
+| `{key: MY_VAR}` | Shorthand — equivalent to `{key: MY_VAR, value: "env:MY_VAR"}` |
+
+The shorthand form uses the key as both the cookie name **and** the env var name. Use the explicit `value: "env:..."` form when the cookie name and the env var name differ (which is common — cookie names often contain characters that aren't valid env var names).
+
+#### Example: proxying an API that requires a session cookie
+
+```yaml
+# api_dock_config/remotes/my_service/1.0.yaml
+name: my_service
+url: https://api.example.com
+
+cookies:
+  - key: __Secure-authjs.session-token
+    value: "env:MY_SERVICE_SESSION_TOKEN"
+```
+
+Set the env var before starting api-dock:
+
+```bash
+export MY_SERVICE_SESSION_TOKEN="your-session-token-here"
+pixi run api-dock start
+```
+
+Every request proxied to `my_service` will include the `__Secure-authjs.session-token` cookie, even if the client did not send one.
+
+#### Injection precedence
+
+If an injected cookie has the same name as a forwarded client cookie, the injected value takes precedence. This ensures the server-side credential is always used, regardless of what the client sends.
+
 ## Authentication Configuration
 
 Configure authentication to validate requests before processing. Multiple authentication methods are supported:
@@ -1080,6 +1129,58 @@ pixi run jupyter lab .
 pixi run python scripts/hello_world.py
 ```
 
+---
+
+---
+
+# Development
+
+## Publishing a Release
+
+```bash
+# 0. Make sure you are on `main` and merged with any changes
+
+# 1. Bump version in pyproject.toml
+
+# 2. Commit everything
+git add -A
+git commit -m "v0.6.0: proxy passthrough fixes, cookie injection"
+
+# 3. Tag and push
+git tag v0.6.0
+git push origin main v0.6.0
+
+# 4. Build the wheel (requires the `dev` pixi environment)
+rm -rf dist/
+find . -name "__pycache__" -type d -exec rm -rf {} +
+find . -name "*.pyc" -delete
+pixi run -e dev python -m build --wheel
+ls dist/*.whl
+
+# 5. Create GitHub release with the wheel attached
+gh release create v0.6.0 dist/api_dock-0.6.0-py3-none-any.whl \
+    --title "v0.6.0" --notes "$(cat <<'EOF'
+* new features
+    - Cookie injection: dict entries in the `cookies` list inject server-side cookies into upstream requests, with `env:MY_VAR` env var support and literal value support
+* bug fixes
+    - Binary responses (image, audio) no longer corrupted — raw bytes passed through with correct content-type
+    - 3xx redirects returned to client when `follow_redirects: false` (previously followed internally, doubling egress)
+    - Upstream response headers (Cache-Control, ETag, Last-Modified, etc.) now forwarded to client
+    - Upstream 4xx/5xx error bodies passed through verbatim (previously wrapped/swallowed)
+    - JSON responses no longer re-serialized — raw bytes returned as-is, preserving exact upstream payload
+* cleanup / other improvements
+    - Added `ProxyResponse` typed dataclass as the return contract for `map_route()` and `map_database_route()`
+    - Added test suite (38 tests covering proxy pipeline and cookie injection)
+    - Removed broken root `__init__.py` that caused pytest import conflicts
+    - Bumped cryptography dependency to >=48.0.0,<49.0.0
+EOF
+)"
+
+# 6. Publish to PyPI
+pixi run -e dev python -m twine upload dist/*.whl
+```
+
+
 ---
 
 # License

{api_dock-0.5.0 → api_dock-0.6.0}/api_dock/cli.py

@@ -459,15 +459,12 @@ def _list_configs() -> None:
 
     # Check for local configs
     local_dir = Path("api_dock_config")
-    config_dir = Path("config")
-
     local_configs = list(local_dir.glob("*.yaml")) if local_dir.exists() else []
-    config_configs = list(config_dir.glob("*.yaml")) if config_dir.exists() else []
 
-    # Check for package configs
+    # Check for bundled example configs
     try:
         import importlib.resources as pkg_resources
-        package_dir = Path(pkg_resources.files("api_dock") / "config")
+        package_dir = Path(pkg_resources.files("api_dock") / "example_api_dock_config")
         package_configs = list(package_dir.glob("*.yaml")) if package_dir.exists() else []
     except Exception:
         package_configs = []
@@ -478,17 +475,11 @@ def _list_configs() -> None:
             click.echo(f"  {config_file.stem}")
         click.echo()
     else:
-        click.echo("📁 Local configurations (api_dock_config/): None")
-        click.echo()
-
-    if config_configs:
-        click.echo("📁 Project configurations (config/):")
-        for config_file in sorted(config_configs):
-            click.echo(f"  {config_file.stem}")
+        click.echo("📁 Local configurations (api_dock_config/): None — run 'api-dock init' to create")
         click.echo()
 
     if package_configs:
-        click.echo("📦 Package configurations:")
+        click.echo("📦 Example configurations (run 'api-dock init' to copy to api_dock_config/):")
         for config_file in sorted(package_configs):
             click.echo(f"  {config_file.stem}")
         click.echo()

{api_dock-0.5.0 → api_dock-0.6.0}/api_dock/config.py

@@ -242,7 +242,10 @@ def get_settings(config: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def get_cookies_config(config: Dict[str, Any]) -> List[str]:
-    """Extract cookie configuration from config.
+    """Extract cookie names to forward from incoming requests.
+
+    Only string entries in the ``cookies`` list are returned here. Dict entries
+    (cookie injection) are handled separately by ``resolve_inject_cookies``.
 
     Args:
         config: Configuration dictionary (main, remote, or database).
@@ -254,9 +257,7 @@ def get_cookies_config(config: Dict[str, Any]) -> List[str]:
     if not isinstance(cookies, list):
         return []
 
-    # Ensure all cookie names are strings
-    cookie_list = [str(cookie) for cookie in cookies if cookie]
-    return cookie_list
+    return [str(c) for c in cookies if c and isinstance(c, str)]
 
 
 def filter_cookies_by_config(cookies: Dict[str, str], config: Dict[str, Any]) -> Dict[str, str]:
@@ -288,23 +289,26 @@ def filter_cookies_by_config(cookies: Dict[str, str], config: Dict[str, Any]) ->
             else:
                 return {}
 
-    # Handle list of cookie names (existing behavior)
+    # Handle list — may contain string names (forward from client) and/or
+    # dict entries (inject from config/env var).
     elif isinstance(cookies_setting, list):
+        injected = resolve_inject_cookies(config)
         allowed_cookies = get_cookies_config(config)
+
         if not allowed_cookies:
-            # Empty list means no cookies allowed except authentication key
+            # No string entries — only auth key forwarded from client, plus injected.
+            result: Dict[str, str] = {}
             if auth_key and auth_key in cookies:
-                auth_only = {auth_key: cookies[auth_key]}
-                return auth_only
-            else:
-                return {}
+                result[auth_key] = cookies[auth_key]
+            result.update(injected)
+            return result
 
-        # Always include authentication key in allowed cookies
+        # Always include authentication key in forwarded set.
         if auth_key and auth_key not in allowed_cookies:
             allowed_cookies = allowed_cookies + [auth_key]
 
-        # Filter cookies to only include allowed ones
         filtered = {k: v for k, v in cookies.items() if k in allowed_cookies}
+        filtered.update(injected)
         return filtered
 
     # Default: no cookie configuration means only authentication key passed
@@ -316,6 +320,56 @@ def filter_cookies_by_config(cookies: Dict[str, str], config: Dict[str, Any]) ->
             return {}
 
 
+def resolve_inject_cookies(config: Dict[str, Any]) -> Dict[str, str]:
+    """Resolve dict entries in the ``cookies`` list into ready-to-send cookie values.
+
+    The ``cookies`` list accepts a mix of strings (names of client cookies to forward)
+    and dicts (cookies to inject into the outgoing request regardless of what the
+    client sent). This function handles the dict entries only.
+
+    Dict entry forms:
+
+    - ``{key: COOKIE_NAME, value: "literal-value"}`` — inject with a literal string.
+    - ``{key: COOKIE_NAME, value: "env:MY_ENV_VAR"}`` — inject with the value of
+      environment variable ``MY_ENV_VAR``; resolves to empty string if unset.
+    - ``{key: MY_ENV_VAR}`` — shorthand: no ``value`` means look up an env var whose
+      name equals the key (equivalent to ``{key: MY_ENV_VAR, value: "env:MY_ENV_VAR"}``).
+
+    Example YAML::
+
+        cookies:
+          - session_id                           # forward from client request
+          - key: __Secure-authjs.session-token
+            value: "env:SOUNDHUB_SESSION_TOKEN"  # inject from env var
+
+    Args:
+        config: Configuration dictionary (main, remote, or database).
+
+    Returns:
+        Dictionary mapping cookie names to their resolved string values.
+    """
+    cookies_setting = config.get("cookies", [])
+    if not isinstance(cookies_setting, list):
+        return {}
+
+    result: Dict[str, str] = {}
+    for entry in cookies_setting:
+        if not isinstance(entry, dict):
+            continue
+        key = entry.get("key")
+        if not key or not isinstance(key, str):
+            continue
+        raw_value = entry.get("value")
+        if raw_value is None:
+            value = os.environ.get(key, "")
+        elif isinstance(raw_value, str) and raw_value.startswith("env:"):
+            value = os.environ.get(raw_value[4:], "")
+        else:
+            value = str(raw_value)
+        result[key] = value
+    return result
+
+
 def get_authentication_config(config: Dict[str, Any]) -> Optional[Dict[str, Any]]:
     """Extract authentication configuration from config.
 
@@ -337,8 +391,6 @@ def get_authentication_config(config: Dict[str, Any]) -> Optional[Dict[str, Any]
     if "encrypted" not in auth_config:
         auth_config["encrypted"] = DEFAULT_AUTH_SETTINGS["encrypted"]
 
-    auth_key = auth_config.get("key", "UNKNOWN")
-    auth_method = auth_config.get("method", "UNKNOWN")
     return auth_config
 
 

{api_dock-0.5.0 → api_dock-0.6.0}/api_dock/config_discovery.py

@@ -31,9 +31,8 @@ def find_config(config_name: Optional[str] = None) -> Optional[str]:
     """Find configuration file by name.
 
     Search order:
-    1. api_dock_config/<config_name>.yaml
-    2. config/<config_name>.yaml
-    3. api_dock/config/<config_name>.yaml (package default)
+    1. api_dock_config/<config_name>.yaml  (local user config)
+    2. api_dock/example_api_dock_config/<config_name>.yaml  (bundled package default)
 
     Args:
         config_name: Config name without .yaml extension (default: "config").
@@ -48,20 +47,15 @@ def find_config(config_name: Optional[str] = None) -> Optional[str]:
     if config_name.endswith(".yaml"):
         config_name = config_name[:-5]
 
-    # Check local config directory
+    # Check local config directory first
     local_path = Path(f"{LOCAL_CONFIG_DIR}/{config_name}.yaml")
     if local_path.exists():
         return str(local_path)
 
-    # Check config/ directory
-    config_path = Path(f"config/{config_name}.yaml")
-    if config_path.exists():
-        return str(config_path)
-
-    # Check package config directory
+    # Fall back to bundled package examples
     try:
         import importlib.resources as pkg_resources
-        package_config = Path(pkg_resources.files("api_dock") / "config" / f"{config_name}.yaml")
+        package_config = Path(pkg_resources.files("api_dock") / "example_api_dock_config" / f"{config_name}.yaml")
         if package_config.exists():
             return str(package_config)
     except Exception:
@@ -91,7 +85,7 @@ def init_config() -> bool:
         (local_dir / "remotes").mkdir(exist_ok=True)
         (local_dir / "databases").mkdir(exist_ok=True)
 
-        # Step 3: Copy default configs from package
+        # Step 3: Copy example configs from package
         package_dir = _get_package_config_dir()
         if not package_dir:
             return False
@@ -130,14 +124,14 @@ def init_config() -> bool:
 # INTERNAL
 #
 def _get_package_config_dir() -> Optional[Path]:
-    """Get the path to the package's config directory.
+    """Get the path to the bundled example config directory inside the package.
 
     Returns:
-        Path to package config directory, or None if not found.
+        Path to example_api_dock_config directory, or None if not found.
     """
     try:
         import importlib.resources as pkg_resources
-        config_dir = Path(pkg_resources.files("api_dock") / "config")
+        config_dir = Path(pkg_resources.files("api_dock") / "example_api_dock_config")
         return config_dir if config_dir.exists() else None
     except Exception:
         return None

api_dock-0.6.0/api_dock/example_api_dock_config/config.yaml

@@ -0,0 +1,22 @@
+name: my-api
+description: My API Dock instance
+authors:
+  - Your Name
+
+# Remote APIs to proxy (add a file per remote in remotes/)
+remotes:
+  - example_remote
+
+# SQL databases to query (add a file per database in databases/)
+databases:
+  - example_db
+
+settings:
+  add_trailing_slash: false   # Set true to auto-append trailing slash to proxied paths
+  follow_redirects: true      # Set false to pass 3xx redirects through to the client
+
+# Global route restrictions — applied to all remotes unless overridden per-remote.
+# Uncomment to block DELETE on every remote:
+# restricted:
+#   - route: "*"
+#     method: delete

api_dock-0.6.0/api_dock/example_api_dock_config/databases/example_db.yaml

@@ -0,0 +1,75 @@
+name: example_db
+description: Example database
+authors:
+  - API Team
+
+# Table definitions — supports S3, GCS, HTTPS, and local paths.
+# Use **/* for partitioned Parquet (e.g. Hive-partitioned directories).
+tables:
+  items: s3://your-bucket/items.parquet
+  # items: gs://your-bucket/items.parquet        # Google Cloud Storage
+  # items: https://host/path/items.parquet        # HTTPS
+  # items: data/items.parquet                     # local file
+
+routes:
+  # List all items with optional filtering, sorting, and pagination.
+  - route: items
+    sql: SELECT [[items]].* FROM [[items]]
+    query_params:
+      # WHERE clause filter — only applied when the param is present in the URL.
+      - category:
+          sql: "[[items]].category = '{{category}}'"
+
+      # Sorting — sql_append clauses are appended after the WHERE clause in YAML order.
+      - sort:
+          sql_append: ORDER BY {{sort}} {{direction}}
+          default: id        # used when ?sort= is not provided
+      - direction:
+          default: ASC       # value-only param — feeds into sort's template
+
+      # Pagination
+      - limit:
+          sql_append: LIMIT {{limit}}
+          default: 50
+      - offset:
+          sql_append: OFFSET {{offset}}
+
+  # Fetch a single item by ID.
+  - route: items/{{id}}
+    sql: SELECT [[items]].* FROM [[items]] WHERE [[items]].id = {{id}}
+
+
+# ── Advanced features (uncomment to use) ─────────────────────────────────────
+
+# Named queries — define reusable SQL fragments and reference them with [[name]].
+# queries:
+#   items_with_meta: |
+#     SELECT [[items]].*, [[meta]].label
+#     FROM [[items]]
+#     JOIN [[meta]] ON [[items]].id = [[meta]].item_id
+
+# Required parameter with a custom error response (returns 400 if missing).
+# - route: items/search
+#   sql: SELECT [[items]].* FROM [[items]]
+#   query_params:
+#     - q:
+#         sql: "[[items]].name ILIKE '%{{q}}%'"
+#         required: true
+#         missing_response:
+#           error: "q is required"
+#           http_status: 400
+
+# Conditional parameter — branch on the parameter's value.
+# - status:
+#     conditional:
+#       active:
+#         sql: "[[items]].active = true"
+#       inactive:
+#         sql: "[[items]].active = false"
+#       default:
+#         response: "Unknown status — use active or inactive"
+
+# Direct response — return a fixed JSON response without executing SQL.
+# - debug:
+#     response:
+#       message: "Debug mode — no query executed"