queryapigate 0.5.0__py3-none-any.whl

queryapigate/cache.py

@@ -0,0 +1,61 @@
+"""Opt-in, in-process TTL response cache for saved queries.
+
+Never applies to ad-hoc ``/execute_sql`` (there is no stable name to hang a TTL off), and the caller
+(``run_saved`` in ``app.py``) only ever consults this cache for a saved query whose SQL is read-only -
+serving a cached response in place of a write would silently skip that write. Cache keys already include
+the resolved parameter values, connection, format and page, so entries are shared across API keys that can
+both use the same connection - that reveals nothing a scoped key could not already see by running the
+query itself.
+
+Like ``ratelimit.RateLimiter``, one instance lives per Flask app (``app.extensions['queryapigate_cache']``) so
+tests get a clean cache instead of leaking entries between them; a multi-process deployment would need a
+shared backing store instead of this one process's memory.
+"""
+import hashlib
+import json
+import threading
+import time
+from collections import OrderedDict
+
+MAX_ENTRIES = 10_000  # bounds memory; the least recently used entry is evicted first
+
+
+class ResponseCache:
+    def __init__(self, clock=time.monotonic):
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._entries = OrderedDict()  # key -> (body, content_type, headers, etag, expires_at)
+
+    @staticmethod
+    def key(**parts):
+        """A stable cache key from whatever makes the response unique (name, version, connection, resolved
+        parameter values, format, page, page_size - never raw, unresolved input)."""
+        blob = json.dumps(parts, sort_keys=True, default=str)
+        return hashlib.sha256(blob.encode('utf-8')).hexdigest()
+
+    def get(self, key):
+        """(body, content_type, headers, etag) for a live entry, or None if missing or expired."""
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is None:
+                return None
+            body, content_type, headers, etag, expires_at = entry
+            if self._clock() >= expires_at:
+                del self._entries[key]
+                return None
+            self._entries.move_to_end(key)  # most recently used
+            return body, content_type, headers, etag
+
+    def set(self, key, body, content_type, headers, ttl):
+        """Store a response and return its ETag (a hash of the body, so it changes only when content does)."""
+        etag = hashlib.sha256(body).hexdigest()
+        with self._lock:
+            self._entries[key] = (body, content_type, headers, etag, self._clock() + ttl)
+            self._entries.move_to_end(key)
+            while len(self._entries) > MAX_ENTRIES:
+                self._entries.popitem(last=False)
+        return etag
+
+    def size(self):
+        with self._lock:
+            return len(self._entries)

queryapigate/cli.py

@@ -0,0 +1,168 @@
+"""Command line entry point: ``queryapigate serve``, ``queryapigate init`` and ``queryapigate export``."""
+import argparse
+import logging
+import os
+import sys
+from datetime import datetime
+
+from . import __version__, config, store
+from .app import create_app
+
+LOOPBACK_HOSTS = ('127.0.0.1', 'localhost', '::1')
+
+
+def _serve(args):
+    try:
+        app = create_app()
+    except ValueError as error:  # a malformed setting, e.g. QUERYAPIGATE_RATE_LIMIT
+        print(f'queryapigate: {error}', file=sys.stderr)
+        return 2
+    if args.host not in LOOPBACK_HOSTS and not config.api_key():
+        logging.getLogger('queryapigate').warning(
+            'Listening on %s without QUERYAPIGATE_API_KEY set: anyone who can reach this port can run SQL '
+            'on your active connections.', args.host)
+    logging.getLogger('queryapigate').info('Using %s (connections: %s)', config.home(), config.connections_file().name)
+    app.run(host=args.host, port=args.port, debug=args.debug)
+    return 0
+
+
+def _init(args):
+    home = config.home()
+    home.mkdir(parents=True, exist_ok=True)
+    (home / 'saved_sql').mkdir(exist_ok=True)
+    target = config.connections_file()
+    if target.exists():
+        print(f'{target} already exists - left untouched')
+    else:
+        store.write_json_atomic(str(target), config.EXAMPLE_CONNECTIONS)
+        print(f'Created {target}\nEdit it, set "active": true on the connections you want, '
+              'then run: queryapigate serve')
+    return 0
+
+
+def _resolve_export_path(template, name):
+    """Fill in a --out template's {date}/{name} placeholders. Deliberately just these two, not a general
+    strftime/templating facility - the exact shape #31 was scoped to."""
+    try:
+        return template.format(date=datetime.now().strftime('%Y-%m-%d'), name=name)
+    except (KeyError, IndexError) as error:
+        raise ValueError(f'--out has an unknown placeholder ({error}) - only {{date}} and {{name}} are '
+                         'supported') from None
+
+
+def _export(args):
+    """``queryapigate export <query> --format csv --out /path/{date}.csv`` - the last small step a
+    cron/systemd/Kubernetes CronJob needs to turn the existing ?stream=true export into a scheduled file
+    drop, without becoming a scheduler itself (see BACKLOG.md #31 for why that stays out of scope). Runs
+    entirely in-process against QUERYAPIGATE_HOME - no server needs to be running, no HTTP round trip, no API
+    key: this is a trusted local operator with the same reach the admin key already has."""
+    try:
+        config.check_settings()
+    except ValueError as error:
+        print(f'queryapigate export: {error}', file=sys.stderr)
+        return 2
+
+    from .engine import stream_sql
+    from .errors import ApiError
+    from .formats import STREAM_FORMATTERS, iter_stream_chunks
+    from .params import resolve as resolve_params
+    from .sqltools import fill_placeholders, placeholder_names
+
+    tmp_path = None
+    try:
+        if args.format not in STREAM_FORMATTERS:
+            raise ApiError(f"--format must be one of: {', '.join(sorted(STREAM_FORMATTERS))}")
+        try:
+            raw_params = dict(p.split('=', 1) for p in args.param)
+        except ValueError:
+            raise ApiError('--param must look like name=value') from None
+
+        path = store.resolve_saved_file(args.query)
+        name = store.query_name(path)
+        _, saved = store.select_version(store.load_versions(path), None)
+        connection_name = args.connection or saved.get('connection_name')
+        if not connection_name:
+            raise ApiError('Connection name is missing - pass --connection or set one on the saved query')
+        sql = saved.get('sql_query')
+        if not isinstance(sql, str):
+            raise ApiError('Saved query has no SQL', 500)
+        used = set(placeholder_names(sql))
+        values = resolve_params(saved.get('query_parameters'), raw_params, used=used)
+        sql = fill_placeholders(sql, values)
+
+        out_path = _resolve_export_path(args.out, name)
+        out_dir = os.path.dirname(out_path) or '.'
+        os.makedirs(out_dir, exist_ok=True)
+        tmp_path = os.path.join(out_dir, f'.{os.path.basename(out_path)}.part')
+
+        columns, rows = stream_sql(sql, connection_name, values, config.effective_timeout(args.timeout))
+        row_count = 0
+
+        def counted(row_iter):
+            nonlocal row_count
+            for row in row_iter:
+                row_count += 1
+                yield row
+
+        with open(tmp_path, 'w', newline='') as f:
+            for chunk in iter_stream_chunks(args.format, columns, counted(rows)):
+                f.write(chunk)
+        os.replace(tmp_path, out_path)
+    except ApiError as error:
+        print(f'queryapigate export: {error.message}', file=sys.stderr)
+        return 1
+    except (OSError, ValueError) as error:
+        print(f'queryapigate export: {error}', file=sys.stderr)
+        return 1
+    finally:
+        if tmp_path is not None and os.path.exists(tmp_path):
+            os.remove(tmp_path)  # only ever left behind by a failed run - a success already renamed it away
+
+    print(f'Wrote {row_count} row{"" if row_count == 1 else "s"} to {out_path}')
+    return 0
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(prog='queryapigate', description='Expose SQL databases as a REST API.')
+    parser.add_argument('--version', action='version', version=f'queryapigate {__version__}')
+    commands = parser.add_subparsers(dest='command')
+
+    serve = commands.add_parser('serve', help='start the HTTP server (default)')
+    serve.add_argument('--host', default=os.environ.get('QUERYAPIGATE_HOST', '127.0.0.1'))
+    serve.add_argument('--port', type=int, default=int(os.environ.get('QUERYAPIGATE_PORT', 5000)))
+    serve.add_argument('--debug', action='store_true', default=config.env_flag('QUERYAPIGATE_DEBUG'),
+                       help='Flask debug mode - never use on a reachable host')
+    serve.set_defaults(func=_serve)
+
+    init = commands.add_parser('init', help='create db_connections.json and saved_sql/ in the home folder')
+    init.set_defaults(func=_init)
+
+    export = commands.add_parser('export', help='run a saved query and write the full result to a file '
+                                               '(for cron/systemd/Kubernetes CronJob, not a scheduler itself)')
+    export.add_argument('query', help='saved query name (as used in a GET /q/<name> request)')
+    export.add_argument('--format', choices=('csv', 'tsv', 'ndjson'), default='csv')
+    export.add_argument('--connection', help='overrides the saved query\'s own default connection')
+    export.add_argument('--out', required=True,
+                        help='output path; {date} (YYYY-MM-DD) and {name} are filled in, e.g. '
+                             '/exports/{name}_{date}.csv - written to a temp file and renamed into place '
+                             'only on success, so a failed run never leaves a partial or missing file there')
+    export.add_argument('--param', action='append', default=[], metavar='name=value',
+                        help='a query parameter, e.g. --param customer_id=42 (repeatable)')
+    export.add_argument('--timeout', type=float, help='seconds allowed for the query (default: the server '
+                                                       'setting, QUERYAPIGATE_QUERY_TIMEOUT)')
+    export.set_defaults(func=_export)
+
+    for sub in (serve, init, export):
+        sub.add_argument('--home', help='folder holding db_connections.json and saved_sql/ '
+                                        '(default: $QUERYAPIGATE_HOME or the current directory)')
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        args = parser.parse_args(['serve', *(argv or [])])
+    if getattr(args, 'home', None):
+        os.environ['QUERYAPIGATE_HOME'] = args.home
+    return args.func(args)

queryapigate/config.py

@@ -0,0 +1,268 @@
+"""Runtime configuration, read from environment variables at call time."""
+import os
+import re
+from pathlib import Path
+
+SUPPORTED_DB_TYPES = ('mysql', 'postgres', 'clickhouse', 'sqlite', 'h2', 'jdbc', 'duckdb')
+PASSWORD_MASK = '********'
+CONNECT_TIMEOUT = 10  # seconds
+HISTORY_LIMIT = 50  # executions remembered per saved-query version
+AUDIT_LOG_LIMIT = 500  # administrative-action entries remembered across the whole server
+DEFAULT_QUERY_TIMEOUT = 30.0  # seconds
+DEFAULT_POOL_SIZE = 5  # idle connections kept per distinct connection
+DEFAULT_POOL_IDLE_TIMEOUT = 300.0  # seconds
+DEFAULT_SLOW_QUERY_THRESHOLD = 1.0  # seconds
+
+# Ships with the package; override with QUERYAPIGATE_H2_JAR to use a different H2 version.
+BUNDLED_H2_JAR = Path(__file__).parent / 'lib' / 'h2-2.2.224.jar'
+
+# Shown by `queryapigate init`. Every entry starts inactive so nothing connects until you opt in.
+EXAMPLE_CONNECTIONS = {
+    'connections': {
+        'example-sqlite': {'db': 'sqlite', 'database': 'example.db', 'active': False},
+        'example-duckdb': {'db': 'duckdb', 'database': 'example.duckdb', 'active': False},
+        'example-postgres': {'db': 'postgres', 'host': 'localhost', 'port': 5432, 'database': 'postgres',
+                             'user': 'postgres', 'password': '${POSTGRES_PASSWORD}', 'active': False},
+        'example-mysql': {'db': 'mysql', 'host': 'localhost', 'port': 3306, 'database': 'mydb',
+                          'user': 'root', 'password': '${MYSQL_PASSWORD}', 'active': False},
+        'example-clickhouse': {'db': 'clickhouse', 'host': 'localhost', 'port': 9000, 'database': 'default',
+                               'user': 'default', 'password': '', 'active': False},
+        'example-h2': {'db': 'h2', 'host': 'localhost', 'database': 'test', 'user': 'SA', 'password': '',
+                       'active': False},
+    }
+}
+
+
+def env_flag(name):
+    return os.environ.get(name, '').strip().lower() in ('1', 'true', 'yes', 'on')
+
+
+def home():
+    """Folder holding db_connections.json and saved_sql/ (QUERYAPIGATE_HOME, default: current directory)."""
+    return Path(os.environ.get('QUERYAPIGATE_HOME') or os.getcwd()).resolve()
+
+
+def connections_file():
+    return home() / 'db_connections.json'
+
+
+def api_keys_file():
+    return home() / 'api_keys.json'
+
+
+def roles_file():
+    return home() / 'roles.json'
+
+
+def audit_log_file():
+    return home() / 'audit_log.json'
+
+
+def audit_log_limit():
+    """Administrative-action entries remembered in audit_log.json (QUERYAPIGATE_AUDIT_LOG_LIMIT), default
+    AUDIT_LOG_LIMIT (500). Always a positive count, never "unbounded" like stream_max_rows() can be: unlike
+    a streaming export, audit_log.json is read and rewritten in full on every single audit event (see
+    store.record_audit()), so letting it grow without bound would turn every administrative action into an
+    ever-slower disk read/write. Raise this for longer retention, or set QUERYAPIGATE_AUDIT_LOG_EXPORT_FILE for
+    retention this cap can never roll off. Validated at startup (check_settings()), the same "fail loudly on
+    a typo" treatment stream_max_rows() gets."""
+    raw = os.environ.get('QUERYAPIGATE_AUDIT_LOG_LIMIT', '').strip()
+    return int(raw) if raw else AUDIT_LOG_LIMIT
+
+
+def audit_log_export_file():
+    """Optional path (QUERYAPIGATE_AUDIT_LOG_EXPORT_FILE) to also append every audit entry to, one JSON object per
+    line, appended only - never capped or rewritten like audit_log.json itself, so retention here doesn't
+    depend on audit_log_limit() being sized generously enough. None when unset (today's behaviour,
+    unchanged): nothing exported beyond audit_log.json's own rolling window."""
+    raw = os.environ.get('QUERYAPIGATE_AUDIT_LOG_EXPORT_FILE', '').strip()
+    return Path(raw) if raw else None
+
+
+def saved_sql_dir():
+    return home() / 'saved_sql'
+
+
+def h2_jar():
+    return os.environ.get('QUERYAPIGATE_H2_JAR') or str(BUNDLED_H2_JAR)
+
+
+def allow_writes():
+    return env_flag('QUERYAPIGATE_ALLOW_WRITES')
+
+
+def api_key():
+    return os.environ.get('QUERYAPIGATE_API_KEY') or None
+
+
+def query_timeout():
+    """Server-wide statement time limit in seconds (QUERYAPIGATE_QUERY_TIMEOUT); None when disabled (set to 0)."""
+    try:
+        value = float(os.environ.get('QUERYAPIGATE_QUERY_TIMEOUT', DEFAULT_QUERY_TIMEOUT))
+    except ValueError:
+        return DEFAULT_QUERY_TIMEOUT
+    if value == 0:
+        return None
+    return value if value > 0 else DEFAULT_QUERY_TIMEOUT
+
+
+def effective_timeout(requested=None):
+    """The limit to enforce: a request may ask for less time than the server allows, never more."""
+    limit = query_timeout()
+    if requested is None:
+        return limit
+    return requested if limit is None else min(requested, limit)
+
+
+def pool_size():
+    """Idle connections kept per distinct connection (QUERYAPIGATE_POOL_SIZE); 0 disables pooling."""
+    try:
+        return max(0, int(os.environ.get('QUERYAPIGATE_POOL_SIZE', DEFAULT_POOL_SIZE)))
+    except ValueError:
+        return DEFAULT_POOL_SIZE
+
+
+def pool_idle_timeout():
+    """Seconds an idle pooled connection is kept before it is closed (QUERYAPIGATE_POOL_IDLE_TIMEOUT)."""
+    try:
+        value = float(os.environ.get('QUERYAPIGATE_POOL_IDLE_TIMEOUT', DEFAULT_POOL_IDLE_TIMEOUT))
+    except ValueError:
+        return DEFAULT_POOL_IDLE_TIMEOUT
+    return value if value > 0 else DEFAULT_POOL_IDLE_TIMEOUT
+
+
+def cors_origins():
+    """Origins allowed to call the API from a browser (QUERYAPIGATE_CORS_ORIGINS): None (off), '*' or a frozenset.
+
+    Entries are compared case-insensitively and without a trailing slash, e.g. https://app.example.com.
+    """
+    raw = os.environ.get('QUERYAPIGATE_CORS_ORIGINS', '').strip()
+    if not raw:
+        return None
+    origins = [item.strip().rstrip('/').lower() for item in raw.split(',') if item.strip()]
+    if '*' in origins:
+        return '*'
+    return frozenset(origins) or None
+
+
+_RATE_PERIODS = {'second': 1, 'minute': 60, 'hour': 3600, 'day': 86400}
+_RATE_RE = re.compile(r'^\s*(\d+)\s*/\s*(second|minute|hour|day)s?\s*$', re.I)
+
+
+def parse_rate_limit(text, label='QUERYAPIGATE_RATE_LIMIT'):
+    """Parse '60/minute' (also second, hour, day) into (requests, seconds); raises ValueError when malformed.
+    ``label`` names the setting in the error message - the default fits this function's own env var, but a
+    caller validating the same grammar for something else (e.g. apikeys.py's per-key rate_limit) should
+    pass its own name so the message doesn't misleadingly point at QUERYAPIGATE_RATE_LIMIT."""
+    match = _RATE_RE.match(text or '')
+    if not match or int(match.group(1)) < 1:
+        raise ValueError(f"{label} must look like '60/minute' (a positive count, then second, minute, "
+                         f"hour or day), not {text!r}")
+    return int(match.group(1)), _RATE_PERIODS[match.group(2).lower()]
+
+
+_RATE_PERIOD_NAMES = {seconds: name for name, seconds in _RATE_PERIODS.items()}
+
+
+def format_rate_limit(rate_limit):
+    """The inverse of parse_rate_limit(): (60, 60) -> '60/minute'. None in, None out - for rendering an
+    already-resolved (requests, seconds) pair (e.g. a Permission's own rate_limit) back into the same
+    human-readable form it was originally configured in."""
+    if rate_limit is None:
+        return None
+    count, seconds = rate_limit
+    return f'{count}/{_RATE_PERIOD_NAMES.get(seconds, str(seconds) + "s")}'
+
+
+def rate_limit():
+    """(requests, seconds) allowed per client (QUERYAPIGATE_RATE_LIMIT), or None when limiting is off."""
+    raw = os.environ.get('QUERYAPIGATE_RATE_LIMIT', '').strip()
+    if not raw:
+        return None
+    try:
+        return parse_rate_limit(raw)
+    except ValueError:
+        return None  # create_app() rejects a malformed value at startup; never limit by accident afterwards
+
+
+def proxy_hops():
+    """Reverse proxies in front of the app whose X-Forwarded-* headers can be trusted (QUERYAPIGATE_TRUST_PROXY)."""
+    try:
+        return max(0, int(os.environ.get('QUERYAPIGATE_TRUST_PROXY', 0)))
+    except ValueError:
+        return 0
+
+
+def check_settings():
+    """Raise ValueError for a malformed setting, so a typo fails at startup instead of silently switching off a
+    protection."""
+    # This project was named SQL2API before it was QueryAPIGate, and its settings were SQL2API_*. They are
+    # deliberately not read any more - but silently ignoring a leftover SQL2API_API_KEY would start the server
+    # with no admin key configured, which means open access. So a leftover old name is a startup error.
+    legacy = sorted(name for name in os.environ if name.startswith('SQL2API_'))
+    if legacy:
+        renamed = ', '.join(f"{name} -> QUERYAPIGATE_{name[len('SQL2API_'):]}" for name in legacy)
+        raise ValueError(f'these settings use the old SQL2API_ prefix, which is no longer read: {renamed}. '
+                         'Rename each one; ignoring them silently could leave the server without an API key')
+    raw = os.environ.get('QUERYAPIGATE_RATE_LIMIT', '').strip()
+    if raw:
+        parse_rate_limit(raw)
+    raw = os.environ.get('QUERYAPIGATE_STREAM_MAX_ROWS', '').strip()
+    if raw and (not raw.isdigit() or int(raw) < 1):
+        raise ValueError('QUERYAPIGATE_STREAM_MAX_ROWS must be a positive integer')
+    raw = os.environ.get('QUERYAPIGATE_AUDIT_LOG_LIMIT', '').strip()
+    if raw and (not raw.isdigit() or int(raw) < 1):
+        raise ValueError('QUERYAPIGATE_AUDIT_LOG_LIMIT must be a positive integer')
+    raw = os.environ.get('QUERYAPIGATE_SECRET_KEY', '').strip()
+    if raw:
+        try:
+            from cryptography.fernet import Fernet
+        except ImportError:
+            raise ValueError('QUERYAPIGATE_SECRET_KEY is set but the "cryptography" package is not installed - '
+                             'run `pip install "queryapigate[encryption]"`') from None
+        try:
+            Fernet(raw.encode('utf-8'))
+        except (ValueError, TypeError):
+            raise ValueError('QUERYAPIGATE_SECRET_KEY must be a valid Fernet key - 32 url-safe base64-encoded '
+                             'bytes, e.g. from `python -c "from cryptography.fernet import Fernet; '
+                             'print(Fernet.generate_key().decode())"`') from None
+
+
+def secret_key():
+    """The server-side key used to encrypt connection passwords at rest (QUERYAPIGATE_SECRET_KEY), or None when
+    unset - encryption at rest is opt-in; without it, a connection's password is stored exactly as given,
+    today's unchanged behaviour. Validated as a real Fernet key at startup by check_settings(), not here."""
+    return os.environ.get('QUERYAPIGATE_SECRET_KEY') or None
+
+
+def max_page_size():
+    try:
+        return max(1, int(os.environ.get('QUERYAPIGATE_MAX_PAGE_SIZE', 1000)))
+    except ValueError:
+        return 1000
+
+
+def stream_max_rows():
+    """Row cap for a streaming (?stream=true) export (QUERYAPIGATE_STREAM_MAX_ROWS), or None when unbounded -
+    today's original behaviour, unchanged unless explicitly opted into. Validated at startup
+    (check_settings()) rather than silently falling back like max_page_size() does: this is a safety cap an
+    admin is deliberately turning on, so a typo should fail loudly, not silently leave it unbounded."""
+    raw = os.environ.get('QUERYAPIGATE_STREAM_MAX_ROWS', '').strip()
+    return int(raw) if raw else None
+
+
+def json_logs():
+    """Emit structured (one JSON object per line) logs instead of plain text (QUERYAPIGATE_JSON_LOGS)."""
+    return env_flag('QUERYAPIGATE_JSON_LOGS')
+
+
+def slow_query_threshold():
+    """Seconds a query may take before it is logged as a warning (QUERYAPIGATE_SLOW_QUERY_THRESHOLD, default 1);
+    None when 0 disables it."""
+    try:
+        value = float(os.environ.get('QUERYAPIGATE_SLOW_QUERY_THRESHOLD', DEFAULT_SLOW_QUERY_THRESHOLD))
+    except ValueError:
+        return DEFAULT_SLOW_QUERY_THRESHOLD
+    if value == 0:
+        return None
+    return value if value > 0 else DEFAULT_SLOW_QUERY_THRESHOLD

queryapigate/cors.py

@@ -0,0 +1,51 @@
+"""Cross-origin (CORS) support for browser clients, off unless QUERYAPIGATE_CORS_ORIGINS is set.
+
+Without it a web page on another origin cannot call the API: browsers refuse to send the JSON requests and to read
+the answers. CORS only tells the *browser* which sites may call; it is not authentication (use QUERYAPIGATE_API_KEY).
+"""
+from flask import Response
+
+from . import config
+
+ALLOWED_METHODS = 'GET, POST, PATCH, DELETE, OPTIONS'
+ALLOWED_HEADERS = 'Content-Type, X-API-Key'
+# Browsers hide response headers a page has not been told about, and pagination depends on these.
+EXPOSED_HEADERS = 'X-Page, X-Page-Size, X-Has-More, X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After'
+PREFLIGHT_MAX_AGE = '600'
+
+
+def allow_origin_value(origin):
+    """The Access-Control-Allow-Origin value for a request from ``origin``, or None when it is not allowed."""
+    allowed = config.cors_origins()
+    if allowed is None or not origin:
+        return None
+    if allowed == '*':
+        return '*'
+    return origin if origin.rstrip('/').lower() in allowed else None
+
+
+def is_preflight(request):
+    return (request.method == 'OPTIONS' and 'Access-Control-Request-Method' in request.headers
+            and config.cors_origins() is not None)
+
+
+def preflight_response(origin):
+    """Answer a browser's permission check before it sends the real request (no auth: it carries no key)."""
+    response = Response(status=204)
+    value = allow_origin_value(origin)
+    if value:
+        response.headers['Access-Control-Allow-Methods'] = ALLOWED_METHODS
+        response.headers['Access-Control-Allow-Headers'] = ALLOWED_HEADERS
+        response.headers['Access-Control-Max-Age'] = PREFLIGHT_MAX_AGE
+        add_headers(response, origin)
+    return response
+
+
+def add_headers(response, origin):
+    value = allow_origin_value(origin)
+    if value:
+        response.headers['Access-Control-Allow-Origin'] = value
+        response.headers['Access-Control-Expose-Headers'] = EXPOSED_HEADERS
+        if value != '*':
+            response.headers.add('Vary', 'Origin')  # the answer depends on who asked
+    return response