api-dock 0.8.1__tar.gz → 0.9.0__tar.gz

{api_dock-0.8.1 → api_dock-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api_dock
-Version: 0.8.1
+Version: 0.9.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-Expression: BSD-3-Clause
@@ -219,19 +219,33 @@ remotes:
 settings:
   add_trailing_slash: true              # Auto-add trailing slash to paths (default: true)
   follow_protocol_downgrades: false     # Allow HTTPS->HTTP redirects (default: false)
+  follow_redirects: true                # Follow remote redirects (default: true)
   timeout: 10                           # Upstream request timeout in seconds (default: 10)
+  base_path: /dock                      # Also serve the API under this prefix (default: none)
+  duckdb:                               # Options for database queries (default: none)
+    memory_limit: 700MB
+    threads: 2
+    max_concurrent_queries: 2
 ```
 
-### HTTP behavior Settings
+### Settings
 
-The optional `settings` section controls HTTP behavior:
+The optional `settings` section controls HTTP and query behavior:
 
 - **`add_trailing_slash`** (default: `true`): Automatically append a trailing slash to all proxied paths. This prevents 307/301 redirects from remote APIs that require trailing slashes (e.g., `/projects` → `/projects/`). Set to `false` to disable this behavior.
 
 - **`follow_protocol_downgrades`** (default: `false`): Control how HTTP redirects are handled. When `false` (recommended), HTTPS→HTTP redirects are blocked for security. When `true`, allows following redirects that downgrade from HTTPS to HTTP (not recommended for production).
 
+- **`follow_redirects`** (default: `true`): Whether redirects from a remote are followed by API Dock (`true`) or passed through to the client with their `Location` header (`false`). Set it to `false` when a remote answers with redirects the client should follow itself, such as presigned S3 URLs for large files.
+
 - **`timeout`** (default: `10`): Upstream request timeout in seconds, applied to both the streaming and buffered proxy paths. Raise it for slow upstreams (e.g. large aggregation queries) that would otherwise return a 502 on timeout. Set to `null` or `false` to disable the timeout entirely (not recommended — a stalled upstream can hold the connection open indefinitely).
 
+- **`base_path`** (default: none): An extra URL prefix the API is also served under, e.g. `/dock`. Use it when a proxy or CDN forwards a path on another domain without stripping it (say CloudFront routes `https://app.example.org/dock/*` to API Dock): `/dock/birdnet/latest/detections/` is then handled as `/birdnet/latest/detections/`. Paths without the prefix keep working, so direct calls and health checks are unaffected.
+
+- **`duckdb`** (default: none): Options for the DuckDB connection each database query runs on. Every key except `max_concurrent_queries` is applied as `SET <key> = <value>`, so any [DuckDB setting](https://duckdb.org/docs/configuration/overview) works; the useful ones on small servers are `memory_limit` (DuckDB spills to disk or fails the query instead of exceeding it), `threads`, and `temp_directory`. `max_concurrent_queries` caps how many database queries run at once in the process; further queries wait their turn. Memory limits apply per query, so on a small instance set `memory_limit × max_concurrent_queries` below the instance's memory.
+
+Database queries run in worker threads, so a slow query doesn't hold up other requests (including health checks on `/`).
+
 ### Catalog Endpoints (`expose`)
 
 The optional `expose` section adds read-only endpoints that list the models and versions of your configured databases, remotes, or both ("sources"). Listings are **opt-in** — with no `expose` key nothing is added.
@@ -411,6 +425,22 @@ Database configurations are stored in `api_dock_config/databases/` directory. Ea
 - **routes**: REST endpoints mapped to SQL queries
 - **schema** (optional): the shared schema (from `databases/config.yaml`) this config's `[[table]]` references fall back to. See [Shared Tables and Schemas](#shared-tables-and-schemas-databasesconfigyaml)
 
+### Startup checks
+
+When API Dock starts, it checks every database and version listed in the main config, from config files and from the shared `databases/config.yaml` (`slugs`), exactly as requests will see them: merged with the main config and with the shared `routes`/`query_params` that apply to that version (after `include`/`exclude`). If anything is wrong it refuses to start and names the database, version, route and template, for example:
+
+```
+ValueError: Database 'owl' version '4.0', route '/detections/{{id}}/overlaps': sql: Table 'all_modelz.detections' not found in database configuration
+```
+
+It checks that:
+- the shared `databases/config.yaml` is valid (`slugs`, `schema_groups`, and the types of its sections)
+- every route and query param has a valid shape
+- no `{{variable}}` is inside a quoted string (other than a string that is exactly one variable, `'{{x}}'`), a quoted identifier, or a SQL comment, and no template ends inside a comment (see [How values reach the database](#how-values-reach-the-database))
+- every `[[table]]`, `[[schema.table]]`, `[[*.table]]` and `[[group.table]]` reference resolves, unions are only used after `FROM`/`JOIN`, and `source_columns` is valid
+
+Database and remote config files are read from the folder that holds the main config file.
+
 ### Syntax
 
 As with the remote-apis, the routes to databases use double-curly-brackets {{}} to reference url variable placeholders.
@@ -713,6 +743,24 @@ Rules:
 ## URL Query Parameters
 
 
+### How values reach the database
+
+api_dock does not paste request values into SQL. Each `{{variable}}` in `sql`, `multivalue_sql`, conditional `sql` and `queries:` becomes a placeholder, and its value (from the path, query string, a `default`, or a cookie) is sent to DuckDB separately. DuckDB converts the value to the column's type, so number, date and boolean filters work as written. A value that is not a valid number, date or boolean for its column, such as `?age=25 OR true`, is rejected with an error instead of being run as SQL.
+
+Because the value is sent separately, **write variables without quotes**:
+
+| Write | Not |
+|---|---|
+| `department = {{department}}` | `department = '{{department}}'` |
+| `UPPER(name) = UPPER({{name}})` | `UPPER(name) = UPPER('{{name}}')` |
+| `name ILIKE '%' \|\| {{name}} \|\| '%'` | `name ILIKE '%{{name}}%'` |
+
+For compatibility with 0.8.x and earlier configs, a string that is exactly one variable (`'{{department}}'`) is read as `{{department}}`. Any other quoted variable, like `'%{{name}}%'`, would be read as literal text, so api_dock refuses to start and prints the route with the fixed form (rewrite it with `||` as in the last row above). A variable can't be used as a column name in double quotes (`"{{column}}"`) either. A variable inside a SQL comment (`-- {{x}}` or `/* {{x}} */`) would be sent with nothing in the query to use it, so api_dock refuses to start and asks you to remove it. A template also can't end inside a comment, because api_dock adds WHERE conditions and `sql_append` clauses after it on the same line: put the comment on its own line or use `/* */`.
+
+`sql_append` works differently. Its values are column names, `ASC`/`DESC` or numbers, which a database can't accept as separate values, so they are written into the SQL text. Each one must contain only letters, digits, spaces and `_ . , ( ) -`, and must not contain `--`. The same applies to the `sql_append` of a [conditional SQL selection](#conditional-sql-selection) branch.
+
+The `# SQL:` comments in the examples below show values in place so the queries are easier to read.
+
 ### Basic Filtering with `sql`
 
 Use `sql` to add WHERE clause fragments. Each fragment is joined with `AND`. Optional by default — only included if the parameter is in the URL.
@@ -725,7 +773,7 @@ routes:
       - age:
           sql: age = {{age}}            # optional — only if ?age= provided
       - department:
-          sql: department = '{{department}}'
+          sql: department = {{department}}
       - height:
           sql: height < {{height}}
           default: 200                  # always included (uses 200 if not in URL)
@@ -741,7 +789,7 @@ GET /db/users
 
 ### Repeated Parameters with `multivalue_sql`
 
-A query parameter key can appear more than once in the URL (e.g. `?recording_id=1&recording_id=4`). Add a `multivalue_sql` template alongside `sql` to handle this: when **more than one** value is passed for the key, `multivalue_sql` is used instead of `sql`, and `{{param}}` expands to a parenthesized, quote-escaped SQL value list suitable for an `IN` clause.
+A query parameter key can appear more than once in the URL (e.g. `?recording_id=1&recording_id=4`). Add a `multivalue_sql` template alongside `sql` to handle this: when **more than one** value is passed for the key, `multivalue_sql` is used instead of `sql`, and `{{param}}` expands to a parenthesized list with one value per URL entry, suitable for an `IN` clause. Each value is sent to the database separately, like any other variable.
 
 Behavior is unchanged when `multivalue_sql` is absent, and when only a single value is passed the normal `sql` template is used.
 
@@ -754,7 +802,7 @@ routes:
           sql: "[[detections]].recording_id = {{recording_id}}"            # single value
           multivalue_sql: "[[detections]].recording_id IN {{recording_id}}"  # 2+ values
       - scientific_name:
-          sql: "[[detections]].scientific_name = '{{scientific_name}}'"
+          sql: "[[detections]].scientific_name = {{scientific_name}}"
 ```
 
 ```bash
@@ -780,7 +828,7 @@ routes:
     query_params:
       # WHERE clause params
       - department:
-          sql: department = '{{department}}'
+          sql: department = {{department}}
       # Post-WHERE params
       - sort:
           sql_append: ORDER BY {{sort}} {{sort_direction}}
@@ -893,13 +941,13 @@ routes:
     query_params:
       # WHERE clause filters
       - name:
-          sql: name ILIKE '%{{name}}%'
+          sql: name ILIKE '%' || {{name}} || '%'
       - age_min:
           sql: age >= {{age_min}}
       - age_max:
           sql: age <= {{age_max}}
       - department:
-          sql: department = '{{department}}'
+          sql: department = {{department}}
       # Sorting and pagination (sql_append)
       - sort:
           sql_append: ORDER BY {{sort}} {{sort_direction}}
@@ -1147,7 +1195,7 @@ Forwarded cookies are accessible in SQL queries using `{{cookies.cookie_name}}`:
 ```yaml
 routes:
   - route: user/profile
-    sql: SELECT * FROM [[users]] WHERE session_id = '{{cookies.session_id}}'
+    sql: SELECT * FROM [[users]] WHERE session_id = {{cookies.session_id}}
 ```
 
 ### Injecting cookies from the server environment
@@ -1490,9 +1538,9 @@ routes:
     sql: SELECT * FROM [[events]]
     query_params:
       - date_from:
-          sql: event_date >= '{{date_from}}'
+          sql: event_date >= {{date_from}}
       - event_type:
-          sql: type = '{{event_type}}'
+          sql: type = {{event_type}}
       - user_id:
           sql: user_id = {{user_id}}
           required: true
@@ -1568,13 +1616,13 @@ tables:
 
 routes:
   - route: my-activity
-    sql: SELECT * FROM [[user_activity]] WHERE user_id = '{{cookies.user_id}}'
+    sql: SELECT * FROM [[user_activity]] WHERE user_id = {{cookies.user_id}}
 
   - route: user-settings
     sql: |
       SELECT * FROM [[user_activity]]
-      WHERE user_id = '{{cookies.user_id}}'
-      AND session_token = '{{cookies.session_token}}'
+      WHERE user_id = {{cookies.user_id}}
+      AND session_token = {{cookies.session_token}}
 ```
 
 ---
@@ -1601,7 +1649,7 @@ Publishing a GitHub Release is what publishes to PyPI: `.github/workflows/publis
 
 ```bash
 # 0. Start from a clean, up-to-date main
-export VERSION=0.8.1          # the NEW version, no leading "v"
+export VERSION=0.9.0          # the NEW version, no leading "v"
 git checkout main
 git pull origin main
 git status
@@ -1612,7 +1660,7 @@ git status
 pixi run -e dev pytest -q
 
 # 3. Commit, tag, push (the commit command adds the "v$VERSION: " prefix)
-export COMMIT_MESSAGE='cross-schema unions, schema groups, source columns'
+export COMMIT_MESSAGE='bound SQL parameters (fix SQL injection) and startup config checks'
 git add -A
 git commit -m "v$VERSION: $COMMIT_MESSAGE"
 git tag "v$VERSION"
@@ -1624,17 +1672,17 @@ gh release create "v$VERSION" \
   --title "v$VERSION" \
   --notes "$(cat <<'EOF'
 * new features
-    - Cross-schema unions: `[[*.table]]` reads a table from every shared schema that has it, and `[[*!.table]]` does the same minus the current database/version's schema
-    - Named `schema_groups` in `databases/config.yaml`, used as `[[group.table]]` / `[[group!.table]]` (validated: known schemas only, no group/schema name clashes)
-    - Route `source_columns` adds where each union row came from (`schema`, `name`, `version`), with default names `schema_name`/`name`/`version` or your own; nothing is added by default
-    - `{{self.schema}}`, `{{self.name}}`, and `{{self.version}}` placeholders for the database/version being queried
-    - Together these support an "overlaps" route shared by every database/version (every detection overlapping a given one across all schemas, except that detection itself); shared query params such as `confidence`, `sort`, and `limit` apply to its rows
+    - Request values are sent to DuckDB as bound parameters, separately from the SQL, so they can never run as SQL. Write variables without quotes (`UPPER(name) = UPPER({{name}})`); a string that is exactly one variable (`'{{name}}'`) still works, and patterns like `'%{{name}}%'` become `'%' || {{name}} || '%'`
+    - Startup checks: API Dock refuses to start, naming the database, version, route and template, if a config has a quoted or commented variable, a template ending in a comment, a malformed route, an invalid shared `databases/config.yaml`, a `[[table]]` / `[[schema.table]]` / union reference that doesn't resolve, or invalid `source_columns`. Each version is checked as requests see it (shared routes/query_params, include/exclude, slugs)
+    - Database and remote configs are read from the folder that holds the main config file
 * bug fixes
-    - A `!` union that removes every member returns no rows (with the right columns) instead of failing, and only the schemas a union actually reads get views and storage credentials
+    - SQL injection: query/path/cookie values were pasted into SQL and only quoted when the SQL fragment happened to contain words like SELECT/WHERE/AND/OR, so filters like `confidence >= {{confidence}}` accepted raw SQL (`?confidence=0 OR 1=1`, `UNION SELECT ... read_csv(...)`)
+    - `response:` bodies are filled in as plain text (they no longer get SQL quotes)
+    - Importing api_dock (or running `api-dock --help`) no longer builds an app from the current directory's config; the default `app`/`fastapi_app`/`flask_app` are built on first use
 * cleanup / other improvements
-    - Added `SqlContext`; `build_sql_query()` / `build_sql_query_with_tables()` accept an optional `context`
-    - README: new "Querying across schemas" section with an overlaps example; example `databases/config.yaml` shows `schema_groups` and a union route
-    - Test suite grew from 198 to 227 tests (`test_schema_unions.py`, including a real DuckDB end-to-end overlaps test)
+    - Removed unused `build_sql_query_legacy` / `_substitute_parameters`; `build_sql_query` returns `(sql, values)` and `build_sql_query_with_tables` returns `(sql, values, tables)`
+    - New `sql_template_check` module and `check_table_references`; README sections "How values reach the database" and "Startup checks"
+    - Test suite grew from 253 to 373 tests
 EOF
 )"
 

{api_dock-0.8.1 → api_dock-0.9.0}/README.md

@@ -180,19 +180,33 @@ remotes:
 settings:
   add_trailing_slash: true              # Auto-add trailing slash to paths (default: true)
   follow_protocol_downgrades: false     # Allow HTTPS->HTTP redirects (default: false)
+  follow_redirects: true                # Follow remote redirects (default: true)
   timeout: 10                           # Upstream request timeout in seconds (default: 10)
+  base_path: /dock                      # Also serve the API under this prefix (default: none)
+  duckdb:                               # Options for database queries (default: none)
+    memory_limit: 700MB
+    threads: 2
+    max_concurrent_queries: 2
 ```
 
-### HTTP behavior Settings
+### Settings
 
-The optional `settings` section controls HTTP behavior:
+The optional `settings` section controls HTTP and query behavior:
 
 - **`add_trailing_slash`** (default: `true`): Automatically append a trailing slash to all proxied paths. This prevents 307/301 redirects from remote APIs that require trailing slashes (e.g., `/projects` → `/projects/`). Set to `false` to disable this behavior.
 
 - **`follow_protocol_downgrades`** (default: `false`): Control how HTTP redirects are handled. When `false` (recommended), HTTPS→HTTP redirects are blocked for security. When `true`, allows following redirects that downgrade from HTTPS to HTTP (not recommended for production).
 
+- **`follow_redirects`** (default: `true`): Whether redirects from a remote are followed by API Dock (`true`) or passed through to the client with their `Location` header (`false`). Set it to `false` when a remote answers with redirects the client should follow itself, such as presigned S3 URLs for large files.
+
 - **`timeout`** (default: `10`): Upstream request timeout in seconds, applied to both the streaming and buffered proxy paths. Raise it for slow upstreams (e.g. large aggregation queries) that would otherwise return a 502 on timeout. Set to `null` or `false` to disable the timeout entirely (not recommended — a stalled upstream can hold the connection open indefinitely).
 
+- **`base_path`** (default: none): An extra URL prefix the API is also served under, e.g. `/dock`. Use it when a proxy or CDN forwards a path on another domain without stripping it (say CloudFront routes `https://app.example.org/dock/*` to API Dock): `/dock/birdnet/latest/detections/` is then handled as `/birdnet/latest/detections/`. Paths without the prefix keep working, so direct calls and health checks are unaffected.
+
+- **`duckdb`** (default: none): Options for the DuckDB connection each database query runs on. Every key except `max_concurrent_queries` is applied as `SET <key> = <value>`, so any [DuckDB setting](https://duckdb.org/docs/configuration/overview) works; the useful ones on small servers are `memory_limit` (DuckDB spills to disk or fails the query instead of exceeding it), `threads`, and `temp_directory`. `max_concurrent_queries` caps how many database queries run at once in the process; further queries wait their turn. Memory limits apply per query, so on a small instance set `memory_limit × max_concurrent_queries` below the instance's memory.
+
+Database queries run in worker threads, so a slow query doesn't hold up other requests (including health checks on `/`).
+
 ### Catalog Endpoints (`expose`)
 
 The optional `expose` section adds read-only endpoints that list the models and versions of your configured databases, remotes, or both ("sources"). Listings are **opt-in** — with no `expose` key nothing is added.
@@ -372,6 +386,22 @@ Database configurations are stored in `api_dock_config/databases/` directory. Ea
 - **routes**: REST endpoints mapped to SQL queries
 - **schema** (optional): the shared schema (from `databases/config.yaml`) this config's `[[table]]` references fall back to. See [Shared Tables and Schemas](#shared-tables-and-schemas-databasesconfigyaml)
 
+### Startup checks
+
+When API Dock starts, it checks every database and version listed in the main config, from config files and from the shared `databases/config.yaml` (`slugs`), exactly as requests will see them: merged with the main config and with the shared `routes`/`query_params` that apply to that version (after `include`/`exclude`). If anything is wrong it refuses to start and names the database, version, route and template, for example:
+
+```
+ValueError: Database 'owl' version '4.0', route '/detections/{{id}}/overlaps': sql: Table 'all_modelz.detections' not found in database configuration
+```
+
+It checks that:
+- the shared `databases/config.yaml` is valid (`slugs`, `schema_groups`, and the types of its sections)
+- every route and query param has a valid shape
+- no `{{variable}}` is inside a quoted string (other than a string that is exactly one variable, `'{{x}}'`), a quoted identifier, or a SQL comment, and no template ends inside a comment (see [How values reach the database](#how-values-reach-the-database))
+- every `[[table]]`, `[[schema.table]]`, `[[*.table]]` and `[[group.table]]` reference resolves, unions are only used after `FROM`/`JOIN`, and `source_columns` is valid
+
+Database and remote config files are read from the folder that holds the main config file.
+
 ### Syntax
 
 As with the remote-apis, the routes to databases use double-curly-brackets {{}} to reference url variable placeholders.
@@ -674,6 +704,24 @@ Rules:
 ## URL Query Parameters
 
 
+### How values reach the database
+
+api_dock does not paste request values into SQL. Each `{{variable}}` in `sql`, `multivalue_sql`, conditional `sql` and `queries:` becomes a placeholder, and its value (from the path, query string, a `default`, or a cookie) is sent to DuckDB separately. DuckDB converts the value to the column's type, so number, date and boolean filters work as written. A value that is not a valid number, date or boolean for its column, such as `?age=25 OR true`, is rejected with an error instead of being run as SQL.
+
+Because the value is sent separately, **write variables without quotes**:
+
+| Write | Not |
+|---|---|
+| `department = {{department}}` | `department = '{{department}}'` |
+| `UPPER(name) = UPPER({{name}})` | `UPPER(name) = UPPER('{{name}}')` |
+| `name ILIKE '%' \|\| {{name}} \|\| '%'` | `name ILIKE '%{{name}}%'` |
+
+For compatibility with 0.8.x and earlier configs, a string that is exactly one variable (`'{{department}}'`) is read as `{{department}}`. Any other quoted variable, like `'%{{name}}%'`, would be read as literal text, so api_dock refuses to start and prints the route with the fixed form (rewrite it with `||` as in the last row above). A variable can't be used as a column name in double quotes (`"{{column}}"`) either. A variable inside a SQL comment (`-- {{x}}` or `/* {{x}} */`) would be sent with nothing in the query to use it, so api_dock refuses to start and asks you to remove it. A template also can't end inside a comment, because api_dock adds WHERE conditions and `sql_append` clauses after it on the same line: put the comment on its own line or use `/* */`.
+
+`sql_append` works differently. Its values are column names, `ASC`/`DESC` or numbers, which a database can't accept as separate values, so they are written into the SQL text. Each one must contain only letters, digits, spaces and `_ . , ( ) -`, and must not contain `--`. The same applies to the `sql_append` of a [conditional SQL selection](#conditional-sql-selection) branch.
+
+The `# SQL:` comments in the examples below show values in place so the queries are easier to read.
+
 ### Basic Filtering with `sql`
 
 Use `sql` to add WHERE clause fragments. Each fragment is joined with `AND`. Optional by default — only included if the parameter is in the URL.
@@ -686,7 +734,7 @@ routes:
       - age:
           sql: age = {{age}}            # optional — only if ?age= provided
       - department:
-          sql: department = '{{department}}'
+          sql: department = {{department}}
       - height:
           sql: height < {{height}}
           default: 200                  # always included (uses 200 if not in URL)
@@ -702,7 +750,7 @@ GET /db/users
 
 ### Repeated Parameters with `multivalue_sql`
 
-A query parameter key can appear more than once in the URL (e.g. `?recording_id=1&recording_id=4`). Add a `multivalue_sql` template alongside `sql` to handle this: when **more than one** value is passed for the key, `multivalue_sql` is used instead of `sql`, and `{{param}}` expands to a parenthesized, quote-escaped SQL value list suitable for an `IN` clause.
+A query parameter key can appear more than once in the URL (e.g. `?recording_id=1&recording_id=4`). Add a `multivalue_sql` template alongside `sql` to handle this: when **more than one** value is passed for the key, `multivalue_sql` is used instead of `sql`, and `{{param}}` expands to a parenthesized list with one value per URL entry, suitable for an `IN` clause. Each value is sent to the database separately, like any other variable.
 
 Behavior is unchanged when `multivalue_sql` is absent, and when only a single value is passed the normal `sql` template is used.
 
@@ -715,7 +763,7 @@ routes:
           sql: "[[detections]].recording_id = {{recording_id}}"            # single value
           multivalue_sql: "[[detections]].recording_id IN {{recording_id}}"  # 2+ values
       - scientific_name:
-          sql: "[[detections]].scientific_name = '{{scientific_name}}'"
+          sql: "[[detections]].scientific_name = {{scientific_name}}"
 ```
 
 ```bash
@@ -741,7 +789,7 @@ routes:
     query_params:
       # WHERE clause params
       - department:
-          sql: department = '{{department}}'
+          sql: department = {{department}}
       # Post-WHERE params
       - sort:
           sql_append: ORDER BY {{sort}} {{sort_direction}}
@@ -854,13 +902,13 @@ routes:
     query_params:
       # WHERE clause filters
       - name:
-          sql: name ILIKE '%{{name}}%'
+          sql: name ILIKE '%' || {{name}} || '%'
       - age_min:
           sql: age >= {{age_min}}
       - age_max:
           sql: age <= {{age_max}}
       - department:
-          sql: department = '{{department}}'
+          sql: department = {{department}}
       # Sorting and pagination (sql_append)
       - sort:
           sql_append: ORDER BY {{sort}} {{sort_direction}}
@@ -1108,7 +1156,7 @@ Forwarded cookies are accessible in SQL queries using `{{cookies.cookie_name}}`:
 ```yaml
 routes:
   - route: user/profile
-    sql: SELECT * FROM [[users]] WHERE session_id = '{{cookies.session_id}}'
+    sql: SELECT * FROM [[users]] WHERE session_id = {{cookies.session_id}}
 ```
 
 ### Injecting cookies from the server environment
@@ -1451,9 +1499,9 @@ routes:
     sql: SELECT * FROM [[events]]
     query_params:
       - date_from:
-          sql: event_date >= '{{date_from}}'
+          sql: event_date >= {{date_from}}
       - event_type:
-          sql: type = '{{event_type}}'
+          sql: type = {{event_type}}
       - user_id:
           sql: user_id = {{user_id}}
           required: true
@@ -1529,13 +1577,13 @@ tables:
 
 routes:
   - route: my-activity
-    sql: SELECT * FROM [[user_activity]] WHERE user_id = '{{cookies.user_id}}'
+    sql: SELECT * FROM [[user_activity]] WHERE user_id = {{cookies.user_id}}
 
   - route: user-settings
     sql: |
       SELECT * FROM [[user_activity]]
-      WHERE user_id = '{{cookies.user_id}}'
-      AND session_token = '{{cookies.session_token}}'
+      WHERE user_id = {{cookies.user_id}}
+      AND session_token = {{cookies.session_token}}
 ```
 
 ---
@@ -1562,7 +1610,7 @@ Publishing a GitHub Release is what publishes to PyPI: `.github/workflows/publis
 
 ```bash
 # 0. Start from a clean, up-to-date main
-export VERSION=0.8.1          # the NEW version, no leading "v"
+export VERSION=0.9.0          # the NEW version, no leading "v"
 git checkout main
 git pull origin main
 git status
@@ -1573,7 +1621,7 @@ git status
 pixi run -e dev pytest -q
 
 # 3. Commit, tag, push (the commit command adds the "v$VERSION: " prefix)
-export COMMIT_MESSAGE='cross-schema unions, schema groups, source columns'
+export COMMIT_MESSAGE='bound SQL parameters (fix SQL injection) and startup config checks'
 git add -A
 git commit -m "v$VERSION: $COMMIT_MESSAGE"
 git tag "v$VERSION"
@@ -1585,17 +1633,17 @@ gh release create "v$VERSION" \
   --title "v$VERSION" \
   --notes "$(cat <<'EOF'
 * new features
-    - Cross-schema unions: `[[*.table]]` reads a table from every shared schema that has it, and `[[*!.table]]` does the same minus the current database/version's schema
-    - Named `schema_groups` in `databases/config.yaml`, used as `[[group.table]]` / `[[group!.table]]` (validated: known schemas only, no group/schema name clashes)
-    - Route `source_columns` adds where each union row came from (`schema`, `name`, `version`), with default names `schema_name`/`name`/`version` or your own; nothing is added by default
-    - `{{self.schema}}`, `{{self.name}}`, and `{{self.version}}` placeholders for the database/version being queried
-    - Together these support an "overlaps" route shared by every database/version (every detection overlapping a given one across all schemas, except that detection itself); shared query params such as `confidence`, `sort`, and `limit` apply to its rows
+    - Request values are sent to DuckDB as bound parameters, separately from the SQL, so they can never run as SQL. Write variables without quotes (`UPPER(name) = UPPER({{name}})`); a string that is exactly one variable (`'{{name}}'`) still works, and patterns like `'%{{name}}%'` become `'%' || {{name}} || '%'`
+    - Startup checks: API Dock refuses to start, naming the database, version, route and template, if a config has a quoted or commented variable, a template ending in a comment, a malformed route, an invalid shared `databases/config.yaml`, a `[[table]]` / `[[schema.table]]` / union reference that doesn't resolve, or invalid `source_columns`. Each version is checked as requests see it (shared routes/query_params, include/exclude, slugs)
+    - Database and remote configs are read from the folder that holds the main config file
 * bug fixes
-    - A `!` union that removes every member returns no rows (with the right columns) instead of failing, and only the schemas a union actually reads get views and storage credentials
+    - SQL injection: query/path/cookie values were pasted into SQL and only quoted when the SQL fragment happened to contain words like SELECT/WHERE/AND/OR, so filters like `confidence >= {{confidence}}` accepted raw SQL (`?confidence=0 OR 1=1`, `UNION SELECT ... read_csv(...)`)
+    - `response:` bodies are filled in as plain text (they no longer get SQL quotes)
+    - Importing api_dock (or running `api-dock --help`) no longer builds an app from the current directory's config; the default `app`/`fastapi_app`/`flask_app` are built on first use
 * cleanup / other improvements
-    - Added `SqlContext`; `build_sql_query()` / `build_sql_query_with_tables()` accept an optional `context`
-    - README: new "Querying across schemas" section with an overlaps example; example `databases/config.yaml` shows `schema_groups` and a union route
-    - Test suite grew from 198 to 227 tests (`test_schema_unions.py`, including a real DuckDB end-to-end overlaps test)
+    - Removed unused `build_sql_query_legacy` / `_substitute_parameters`; `build_sql_query` returns `(sql, values)` and `build_sql_query_with_tables` returns `(sql, values, tables)`
+    - New `sql_template_check` module and `check_table_references`; README sections "How values reach the database" and "Startup checks"
+    - Test suite grew from 253 to 373 tests
 EOF
 )"
 

api_dock-0.9.0/api_dock/__init__.py

@@ -0,0 +1,72 @@
+"""
+
+API Dock Core Module
+
+Core functionality for API Dock wrapper.
+
+License: BSD 3-Clause
+
+"""
+#
+# IMPORTS
+#
+from typing import Any
+
+from api_dock.config import (
+    filter_cookies_by_config,
+    find_remote_config,
+    get_authentication_config,
+    get_cookies_config,
+    get_remote_names,
+    load_main_config,
+    merge_inherited_config,
+    validate_authentication_config,
+    validate_cookies_config,
+)
+from api_dock.fast_api import create_app as create_fastapi_app
+from api_dock.flask_api import create_app as create_flask_app
+from api_dock.route_mapper import RouteMapper
+
+
+#
+# CONSTANTS
+#
+# For backward compatibility, default to FastAPI
+create_app = create_fastapi_app
+
+__all__ = [
+    "app", "create_app",
+    "fastapi_app", "create_fastapi_app",
+    "flask_app", "create_flask_app",
+    "load_main_config", "find_remote_config", "get_remote_names",
+    "RouteMapper"
+]
+
+
+#
+# PUBLIC
+#
+def __getattr__(name: str) -> Any:
+    """Return the default apps on first use instead of building them at import.
+
+    ``api_dock.app`` / ``api_dock.fastapi_app`` (FastAPI) and
+    ``api_dock.flask_app`` are built from the default config the first time
+    they are accessed (see ``fast_api.__getattr__``), so importing api_dock no
+    longer requires a valid config in the current directory.
+
+    Args:
+        name: The attribute being looked up.
+
+    Returns:
+        The requested default app.
+
+    Raises:
+        AttributeError: For any other missing attribute.
+    """
+    if name in ("app", "fastapi_app"):
+        from api_dock import fast_api
+        return fast_api.app
+    if name == "flask_app":
+        from api_dock import flask_api
+        return flask_api.app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{api_dock-0.8.1 → api_dock-0.9.0}/api_dock/config.py

@@ -553,7 +553,7 @@ def resolve_latest_version(versions: List[str]) -> Optional[str]:
         return sorted_versions[0]
 
 
-def is_route_allowed(route: str, config: Dict[str, Any], remote_name: Optional[str] = None, version: Optional[str] = None, method: Optional[str] = None) -> bool:
+def is_route_allowed(route: str, config: Dict[str, Any], remote_name: Optional[str] = None, version: Optional[str] = None, method: Optional[str] = None, config_dir: Optional[str] = None) -> bool:
     """Check if a route is allowed based on configuration restrictions.
 
     Args:
@@ -562,6 +562,8 @@ def is_route_allowed(route: str, config: Dict[str, Any], remote_name: Optional[s
         remote_name: Name of the remote API (for remote-specific restrictions).
         version: Version string for versioned remotes.
         method: HTTP method (e.g., "GET", "POST", "DELETE").
+        config_dir: Directory holding the remote config files. If omitted, it
+            is guessed from a few common locations.
 
     Returns:
         True if route is allowed, False otherwise.
@@ -581,9 +583,8 @@ def is_route_allowed(route: str, config: Dict[str, Any], remote_name: Optional[s
         try:
             # Try to infer config_dir by checking which directory exists
             # This is a heuristic to support both default and custom config locations
-            config_dir = None
             remotes = config.get("remotes", [])
-            if remotes:
+            if config_dir is None and remotes:
                 first_remote = remotes[0] if isinstance(remotes[0], str) else remotes[0].get("name") if isinstance(remotes[0], dict) else None
                 if first_remote:
                     # Try common locations