analytics-platform 0.2.1__py3-none-any.whl

analytics_platform/__init__.py

@@ -0,0 +1,483 @@
+"""One package for a site's Python server, run from the analytics dashboard:
+firewall, error monitoring and server analytics. Each module is separate:
+only the ones turned on are loaded, and one failing never stops the others;
+the firewall in particular never waits on reporting. A loaded module can
+also be switched off in the dashboard (Site settings -> Server).
+
+    platform = create_platform(site_id=..., secret=..., endpoint=...)
+
+    # FastAPI / Starlette          # Flask                  # Django: see analytics_platform.django
+    app.add_middleware(            platform.init_flask(app)
+        PlatformMiddleware, platform=platform)
+
+A module is on with True (or its options as a dict) and off with False.
+No dependencies; Python 3.8+.
+"""
+import asyncio
+import time
+
+from .core import Core, SESSION_HEADER, VERSION, header
+
+__all__ = ["create_platform", "Platform", "PlatformMiddleware", "VERSION"]
+
+
+def _load(name, core, opts):
+    if name == "firewall":
+        from .firewall import Firewall
+        return Firewall(core, **opts)
+    if name == "errors":
+        from .errors import Errors
+        return Errors(core, **opts)
+    if name == "analytics":
+        from .analytics import Analytics
+        return Analytics(core, **opts)
+    if name == "performance":
+        from .performance import Performance
+        return Performance(core, **opts)
+    if name == "crawlers":
+        from .crawlers import Crawlers
+        return Crawlers(core, **opts)
+    if name == "forms":
+        from .forms import Forms
+        return Forms(core, **opts)
+    if name == "headers":
+        return _Headers()
+    if name == "audit":
+        from .audit import Audit
+        return Audit(core, **opts)
+    if name == "flags":
+        from .flags import Flags
+        return Flags(core, **opts)
+    if name == "maintenance":
+        from .maintenance import Maintenance
+        return Maintenance(core, **opts)
+    if name == "inventory":
+        from .inventory import Inventory
+        return Inventory(core, **opts)
+    if name == "posture":
+        from .posture import Posture
+        return Posture(core, **opts)
+    if name == "resources":
+        from .resources import Resources
+        return Resources(core, **opts)
+    if name == "proxy":
+        from .proxy import Proxy
+        return Proxy(core, **opts)
+    raise ValueError(name)
+
+
+MODULES = ("proxy", "firewall", "errors", "analytics", "performance", "crawlers", "forms", "headers", "audit", "flags", "maintenance", "inventory", "posture", "resources")
+
+
+class Platform:
+    """site_id, secret (site settings; keep it on the server), endpoint (the
+    collector's URL); trust_proxy (how to find the visitor's address: None
+    uses the connection's, a number of proxies in X-Forwarded-For,
+    "cloudflare"); debug (print send problems); per module True / False / {options}."""
+
+    def __init__(self, site_id, secret, endpoint, trust_proxy=None, debug=False, firewall=True, errors=True, analytics=True,
+                 performance=True, crawlers=True, forms=True, headers=True, audit=True, flags=True, maintenance=True,
+                 inventory=True,
+                 posture=True, resources=True, proxy=True):
+        self.core = Core(site_id, secret, endpoint, debug)
+        if not self.core.valid:
+            print("[analytics-platform] site_id, secret and endpoint are required; nothing is sent and every request passes")
+        settings = {"firewall": firewall, "errors": errors, "analytics": analytics, "performance": performance,
+                    "crawlers": crawlers, "forms": forms,
+                    "headers": headers, "audit": audit, "flags": flags, "maintenance": maintenance, "inventory": inventory,
+                    "posture": posture, "resources": resources, "proxy": proxy}
+        self._modules = {}
+        for name in MODULES:
+            setting = settings[name]
+            if setting is False or setting is None:
+                continue
+            opts = dict(setting) if isinstance(setting, dict) else {}
+            if name == "firewall":
+                opts.setdefault("trust_proxy", trust_proxy)
+            try:
+                self._modules[name] = _load(name, self.core, opts)
+            except Exception as error:
+                print("[analytics-platform] the %s module could not start and is off: %s" % (name, error))
+        self.core.start(list(self._modules))
+
+    # ---- Modules ----
+
+    @property
+    def modules(self):
+        """The modules that are on."""
+        return list(self._modules)
+
+    @property
+    def firewall(self):
+        return self._modules.get("firewall")
+
+    @property
+    def proxy(self):
+        """The first-party proxy: proxy.script_url() and proxy.collect_url()
+        are the two addresses the page's script tag needs, on this site's own
+        domain, so ad blockers have nothing of ours to recognise."""
+        return self._modules.get("proxy")
+
+    def proxy_response(self, path, method="GET", query="", headers=None, body=None, remote=""):
+        """(status, [(name, value)], body) when the address belongs to the
+        proxy, else None. Called first by every integration: a visitor's
+        beacon is our traffic, not a page of the site, so it is answered
+        before the firewall, the crawler count and the timing."""
+        proxy = self._modules.get("proxy")
+        if proxy is None:
+            return None
+        found = proxy.match(path)
+        if found is None:
+            return None
+        kind, rest = found
+        headers = headers or {}
+        firewall = self._modules.get("firewall")
+        ip = firewall.client_ip(remote, headers) if firewall else remote
+        try:
+            return proxy.handle(kind, rest, method=method, query=query, headers=headers, body=body, client_ip=ip)
+        except Exception as error:
+            self.core.log("proxy", "failed:", error)
+            return 502, [], b""
+
+    def capture_exception(self, error, request=None, status=0, kind="handled"):
+        errors = self._modules.get("errors")
+        if errors:
+            errors.capture_exception(error, request=request, status=status, kind=kind)
+
+    def login_failed(self, request_or_ip):
+        """A failed login (bot protection): the address, or a Django, Flask or
+        Starlette request (its address as trust_proxy says)."""
+        firewall = self._modules.get("firewall")
+        if not firewall:
+            return
+        ip = request_or_ip if isinstance(request_or_ip, str) else self.request_ip(request_or_ip)
+        if ip:
+            firewall.login_failed(ip)
+
+    def request_ip(self, request):
+        """The visitor's address for a Django, Flask or Starlette request."""
+        firewall = self._modules.get("firewall")
+        headers = getattr(request, "headers", None) or {}
+        lowered = {str(k).lower(): v for k, v in headers.items()} if hasattr(headers, "items") else {}
+        meta = getattr(request, "META", None)
+        if meta is not None:
+            remote = meta.get("REMOTE_ADDR", "")
+        elif getattr(request, "client", None) is not None:
+            remote = request.client.host or ""
+        else:
+            remote = getattr(request, "remote_addr", "") or ""
+        return firewall.client_ip(remote, lowered) if firewall else remote
+
+    def is_enabled(self, key, user=None, default=False):
+        """A feature flag from the dashboard (user: for rollouts and user lists;
+        default: until the flag is known, or with the module off)."""
+        flags = self._modules.get("flags")
+        return flags.is_enabled(key, user, default) if flags else default
+
+    def maintenance_response(self, remote, headers, path, query):
+        """Maintenance mode: None to let the request through, ("pass", extra
+        headers) to let it through and remember the preview link, or (status,
+        headers, body) for the "back soon" page."""
+        maintenance = self._modules.get("maintenance")
+        if not maintenance:
+            return None
+        firewall = self._modules.get("firewall")
+        try:
+            ip = firewall.client_ip(remote, headers) if firewall else remote
+            return maintenance.decide(ip, path, query, header(headers, "cookie"))
+        except Exception as error:
+            self.core.log("maintenance", "check failed, request passed:", error)
+            return None
+
+    def audit(self, action, actor="", target="", details=None, request=None):
+        """Records who did what (Security -> Audit log). action: e.g.
+        "user.role_changed"; request adds the actor's address and visit."""
+        audit = self._modules.get("audit")
+        if not audit:
+            return
+        try:
+            ip = self.request_ip(request) if request is not None else ""
+            audit.record(action, actor, target, details, ip, self.session_id(request) if request is not None else "")
+        except Exception as error:
+            self.core.log("audit", "could not record:", error)
+
+    def check_form(self, request=None, fields=None, email=None, name=None, form=None):
+        """Form protection: checks a form before you accept it. The form is
+        request.POST (Django) or request.form (Flask), else pass fields (FastAPI:
+        fields=dict(await request.form())). -> {"ok", "spam", "reasons", "checked"};
+        spam goes to Leads -> Spam."""
+        forms = self._modules.get("forms")
+        if not forms:
+            return {"ok": True, "spam": False, "reasons": [], "checked": False}
+        if fields is None and request is not None:
+            source = getattr(request, "POST", None)
+            if source is None:
+                source = getattr(request, "form", None)
+            if source is not None:
+                fields = {k: (source.getlist(k) if hasattr(source, "getlist") and len(source.getlist(k)) > 1 else source.get(k)) for k in source.keys()}
+        try:
+            return forms.check(fields or {}, self.request_ip(request) if request is not None else "", email, name, form)
+        except Exception as error:
+            self.core.log("forms", "could not check a form:", error)
+            return {"ok": True, "spam": False, "reasons": ["unchecked"], "checked": False}
+
+    def track(self, name, fields=None, session_id=""):
+        analytics = self._modules.get("analytics")
+        return analytics.track(name, fields, session_id) if analytics else ""
+
+    def identify(self, user_id, session_id=""):
+        analytics = self._modules.get("analytics")
+        return analytics.identify(user_id, session_id) if analytics else False
+
+    def lead(self, fields, session_id=""):
+        analytics = self._modules.get("analytics")
+        return analytics.lead(fields, session_id) if analytics else None
+
+    def security_headers(self, present=()):
+        """The dashboard's security headers the response doesn't set itself
+        (present: the header names it has)."""
+        if "headers" not in self._modules:
+            return []
+        have = {str(name).lower() for name in present}
+        return [(n, v) for n, v in self.core.security_headers() if n.lower() not in have]
+
+    def time_request(self, method, route, status, started, path=""):
+        """Records a finished request for Server speed (started: time.perf_counter())."""
+        performance = self._modules.get("performance")
+        if performance:
+            try:
+                performance.record(method, route, status, (time.perf_counter() - started) * 1000, path)
+            except Exception as error:
+                self.core.log("performance", "could not time a request:", error)
+
+    def record_crawler(self, user_agent, path, status, started=None, size=0, ip=""):
+        """Records a finished request when it came from a crawler or AI bot
+        (Health → Crawlers). started: time.perf_counter() when it arrived."""
+        crawlers = self._modules.get("crawlers")
+        if crawlers:
+            try:
+                ms = 0 if started is None else (time.perf_counter() - started) * 1000
+                crawlers.middleware(user_agent, path, status, ms, size, ip)
+            except Exception as error:
+                self.core.log("crawlers", "could not count a crawler request:", error)
+
+    @staticmethod
+    def session_id(request):
+        """The browser's visit, from a Django, Flask or Starlette request."""
+        headers = getattr(request, "headers", None)
+        try:
+            value = headers.get(SESSION_HEADER) if headers is not None else ""
+        except Exception:
+            value = ""
+        return value if isinstance(value, str) else ""
+
+    def flush(self):
+        """Sends everything waiting (serverless: before returning)."""
+        for module in self._modules.values():
+            module.flush()
+
+    def close(self):
+        """Stops background work and sends what's waiting."""
+        self.core.stop()
+        for module in self._modules.values():
+            module.close()
+
+    # ---- Requests ----
+
+    def blocked(self, remote, headers, method, path):
+        """(status, body, headers) when the firewall turns the request away,
+        else None. headers: a dict with lowercase names."""
+        firewall = self._modules.get("firewall")
+        if not firewall:
+            return None
+        try:
+            decision = firewall.check(firewall.client_ip(remote, headers), method, path, header(headers, "user-agent"))
+        except Exception as error:
+            self.core.log("firewall", "check failed, request passed:", error)
+            return None
+        if decision["action"] != "block":
+            return None
+        extra = [("Content-Type", "text/plain; charset=utf-8"), ("Cache-Control", "no-store")]
+        if decision["status"] == 429:
+            extra.append(("Retry-After", firewall.retry_after()))
+            return 429, b"Too Many Requests", extra
+        return 403, b"Forbidden", extra
+
+    def wsgi(self, app, timing=True):
+        """WSGI middleware (Flask, Bottle, Pyramid, plain WSGI). timing=False
+        leaves timing to the framework integration (Flask, which knows the route)."""
+        platform = self
+
+        def middleware(environ, start_response):
+            started = time.perf_counter()
+            headers = {k[5:].replace("_", "-").lower(): v for k, v in environ.items() if k.startswith("HTTP_")}
+            if environ.get("CONTENT_TYPE"):
+                headers["content-type"] = environ["CONTENT_TYPE"]
+            answered = platform.proxy_response(
+                environ.get("PATH_INFO", ""), environ.get("REQUEST_METHOD", ""), environ.get("QUERY_STRING", ""),
+                headers, _wsgi_body(environ), environ.get("REMOTE_ADDR", ""))
+            if answered:
+                status, extra, body = answered
+                start_response("%d " % status, list(extra))
+                return [body]
+            blocked = platform.blocked(environ.get("REMOTE_ADDR", ""), headers, environ.get("REQUEST_METHOD", ""),
+                                       environ.get("PATH_INFO", ""))
+            if blocked:
+                status, body, extra = blocked
+                start_response("%d %s" % (status, body.decode()), extra)
+                return [body]
+            closed = platform.maintenance_response(environ.get("REMOTE_ADDR", ""), headers, environ.get("PATH_INFO", ""), environ.get("QUERY_STRING", ""))
+            if closed and closed[0] != "pass":
+                start_response("503 Service Unavailable", closed[1])
+                return [closed[2]]
+            remember = closed[1] if closed else []
+            seen = {"status": 500}
+
+            def timed_start_response(status, response_headers, exc_info=None):
+                try:
+                    seen["status"] = int(str(status).split(" ", 1)[0])
+                except ValueError:
+                    pass
+                response_headers = list(response_headers) + platform.security_headers(n for n, _ in response_headers) + remember
+                return start_response(status, response_headers, exc_info) if exc_info else start_response(status, response_headers)
+
+            try:
+                return app(environ, timed_start_response)
+            except Exception as error:
+                platform.capture_exception(error, status=500, kind="error", request={
+                    "method": environ.get("REQUEST_METHOD", ""), "path": environ.get("PATH_INFO", ""),
+                    "session_id": headers.get(SESSION_HEADER, ""),
+                })
+                raise
+            finally:
+                if timing:
+                    platform.time_request(environ.get("REQUEST_METHOD", ""), "", seen["status"], started, environ.get("PATH_INFO", ""))
+
+        return middleware
+
+    def init_flask(self, app):
+        """Flask: the firewall in front of the app, and its request errors."""
+        app.wsgi_app = self.wsgi(app.wsgi_app, timing=False)
+        from flask import g, got_request_exception, request
+
+        @app.before_request
+        def _analytics_started():
+            g._analytics_started = time.perf_counter()
+
+        @app.after_request
+        def _analytics_timed(response):
+            started = getattr(g, "_analytics_started", None)
+            if started is not None:
+                rule = getattr(request, "url_rule", None)
+                self.time_request(request.method, getattr(rule, "rule", ""), response.status_code, started, request.path)
+            return response
+
+        def on_error(sender, exception, **_):
+            rule = getattr(request, "url_rule", None)
+            self.capture_exception(exception, status=500, kind="error", request={
+                "method": request.method, "path": request.path, "route": getattr(rule, "rule", ""),
+                "session_id": request.headers.get(SESSION_HEADER, ""),
+            })
+
+        got_request_exception.connect(on_error, app, weak=False)
+        return app
+
+    def asgi(self, app):
+        """ASGI middleware around any ASGI app (FastAPI, Starlette, Django ASGI)."""
+        return PlatformMiddleware(app, platform=self)
+
+
+def _wsgi_body(environ):
+    try:
+        length = int(environ.get("CONTENT_LENGTH") or 0)
+    except ValueError:
+        return b""
+    return environ["wsgi.input"].read(length) if length > 0 else b""
+
+
+class _Headers:
+    """The security headers module: the headers come with the module switches (core)."""
+
+    def flush(self):
+        pass
+
+    def close(self):
+        pass
+
+
+class PlatformMiddleware:
+    """ASGI middleware: app.add_middleware(PlatformMiddleware, platform=platform)."""
+
+    def __init__(self, app, platform):
+        self.app = app
+        self.platform = platform
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            return await self.app(scope, receive, send)
+        headers = {k.decode("latin-1").lower(): v.decode("latin-1") for k, v in scope.get("headers") or []}
+        client = scope.get("client") or ("",)
+        # The tracker's own addresses, answered before anything else: a
+        # visitor's beacon is our traffic, not a page of the site. Sending
+        # runs in a thread, so the event loop keeps turning while it waits.
+        proxy = self.platform.proxy
+        if proxy is not None and proxy.match(scope.get("path", "")) is not None:
+            body = b""
+            while True:
+                message = await receive()
+                body += message.get("body", b"") or b""
+                if not message.get("more_body"):
+                    break
+            answered = await asyncio.get_running_loop().run_in_executor(
+                None,
+                lambda: self.platform.proxy_response(
+                    scope.get("path", ""), scope.get("method", ""),
+                    scope.get("query_string", b"").decode("latin-1"), headers, body, client[0] or ""),
+            )
+            status, extra, out = answered or (404, [], b"")
+            await send({"type": "http.response.start", "status": status,
+                        "headers": [(k.lower().encode(), str(v).encode()) for k, v in extra]})
+            await send({"type": "http.response.body", "body": out})
+            return
+        blocked = self.platform.blocked(client[0] or "", headers, scope.get("method", ""), scope.get("path", ""))
+        if blocked:
+            status, body, extra = blocked
+            await send({"type": "http.response.start", "status": status,
+                        "headers": [(k.lower().encode(), v.encode()) for k, v in extra]})
+            await send({"type": "http.response.body", "body": body})
+            return
+        query = scope.get("query_string", b"").decode("latin-1")
+        closed = self.platform.maintenance_response(client[0] or "", headers, scope.get("path", ""), query)
+        if closed and closed[0] != "pass":
+            await send({"type": "http.response.start", "status": 503, "headers": [(k.lower().encode(), v.encode()) for k, v in closed[1]]})
+            await send({"type": "http.response.body", "body": closed[2]})
+            return
+        remember = [(k.lower().encode(), v.encode()) for k, v in closed[1]] if closed else []
+        started = time.perf_counter()
+        seen = {"status": 500}
+
+        async def timed_send(message):
+            if message.get("type") == "http.response.start":
+                seen["status"] = int(message.get("status") or 500)
+                present = [k.decode("latin-1") for k, _ in message.get("headers") or []]
+                extra = self.platform.security_headers(present)
+                if extra or remember:
+                    message = dict(message, headers=list(message.get("headers") or []) + [(n.lower().encode(), v.encode("latin-1", "replace")) for n, v in extra] + remember)
+            await send(message)
+
+        try:
+            await self.app(scope, receive, timed_send)
+        except Exception as error:
+            self.platform.capture_exception(error, status=500, kind="error", request={
+                "method": scope.get("method", ""), "path": scope.get("path", ""),
+                "route": getattr(scope.get("route"), "path", ""), "session_id": headers.get(SESSION_HEADER, ""),
+            })
+            raise
+        finally:
+            # The router sets scope["route"] (FastAPI, Starlette) on the way in.
+            self.platform.time_request(scope.get("method", ""), getattr(scope.get("route"), "path", "") or "",
+                                       seen["status"], started, scope.get("path", ""))
+
+
+def create_platform(**options):
+    return Platform(**options)

analytics_platform/analytics.py

@@ -0,0 +1,101 @@
+"""Analytics module: what only the server sees for sure (payments, sign-ups,
+plan changes), next to the browser tracker's visits. Not pageviews: the
+tracker counts those, and counting them here too would count them twice.
+
+- track(): events, batched to POST /events/server-events in the background.
+  Each gets an event_uid, so a retried batch can be told apart from new events.
+- identify(): links the browser's visit to your user ID (/events/identify).
+- lead(): adds or updates a lead (/events/lead).
+identify() and lead() wait for the answer (up to 5 seconds).
+Pass session_id to link an event to the visit: the page sends
+window.analyticsSession.getId() in the X-Analytics-Session header, and the
+framework integrations give you platform.session_id(request).
+"""
+import threading
+import uuid
+from datetime import datetime, timezone
+
+from .core import Periodic
+
+BATCH = 100
+QUEUE_MAX = 1000
+FLUSH_EVERY = 2
+RETRY = 15
+
+
+class Analytics:
+    def __init__(self, core, **_):
+        self.core = core
+        self.queue = []
+        self.lock = threading.Lock()
+        self.job = Periodic(self._flush_job, FLUSH_EVERY) if core.valid else None
+
+    def track(self, name, fields=None, session_id=""):
+        """name: the event's name; fields: value, numeric_value, currency, url,
+        event_label, variant, id, timestamp, event_uid (the server events docs).
+        Returns the event_uid, or "" when not queued."""
+        if not name or not isinstance(name, str) or not self.core.is_on("analytics"):
+            return ""
+        fields = dict(fields or {})
+        event = {
+            "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            "session_id": session_id or "",
+        }
+        event.update(fields)
+        event["event_name"] = name[:100]
+        event["event_uid"] = fields.get("event_uid") or str(uuid.uuid4())
+        if isinstance(event.get("numeric_value"), (int, float)):
+            event["numeric_value"] = str(event["numeric_value"])
+        with self.lock:
+            if len(self.queue) >= QUEUE_MAX:
+                self.core.log("analytics", "queue full, event dropped")
+                return ""
+            self.queue.append(event)
+            full = len(self.queue) >= BATCH
+        if full and self.job:
+            self.job.run_now()
+        return event["event_uid"]
+
+    def flush(self):
+        """Sends what's waiting; returns False when some of it must be tried again."""
+        with self.lock:
+            waiting, self.queue = self.queue, []
+        ok = True
+        for i in range(0, len(waiting), BATCH):
+            batch = waiting[i:i + BATCH]
+            res = self.core.send("analytics", "/events/server-events", body={"events": batch})
+            if res is None or res.status == 429 or res.status >= 500:
+                ok = False
+                with self.lock:
+                    self.queue = (batch + self.queue)[:QUEUE_MAX]
+            elif not res.ok:
+                self.core.log("analytics", "events refused:", res.body[:300])
+        return ok
+
+    def _flush_job(self):
+        return FLUSH_EVERY if self.flush() else RETRY
+
+    def identify(self, user_id, session_id=""):
+        """Links the visit to your user ID. True when stored."""
+        if not user_id or not session_id or not self.core.is_on("analytics"):
+            return False
+        res = self.core.send("analytics", "/events/identify", body={"user_id": str(user_id), "session_id": session_id})
+        return bool(res and res.ok)
+
+    def lead(self, fields, session_id=""):
+        """fields: email or phone, and name, status, tags, note, deal fields...
+        Returns {"status", "lead_id"}, or None."""
+        if not self.core.is_on("analytics"):
+            return None
+        res = self.core.send("analytics", "/events/lead", body=dict({"session_id": session_id or ""}, **(fields or {})))
+        if res is None:
+            return None
+        if not res.ok:
+            self.core.log("analytics", "lead refused:", res.body[:300])
+            return None
+        return res.json()
+
+    def close(self):
+        if self.job:
+            self.job.stop()
+        self.flush()

analytics_platform/audit.py

@@ -0,0 +1,53 @@
+"""Audit log module: who did what on your site, sent to POST /events/audit in
+small batches in the background (Security -> Audit log).
+audit("user.role_changed", actor=..., target=..., details=..., request=...);
+the request adds the actor's address and visit. What goes in (names, emails)
+is up to you. Django's logins and logouts are recorded on their own.
+"""
+import threading
+from datetime import datetime, timezone
+
+from .core import Periodic
+
+BATCH = 100
+QUEUE_MAX = 1000
+FLUSH_EVERY = 5
+
+
+class Audit:
+    def __init__(self, core, **_):
+        self.core = core
+        self.queue = []
+        self.lock = threading.Lock()
+        self.job = Periodic(self._flush_job, FLUSH_EVERY) if core.valid else None
+
+    def record(self, action, actor="", target="", details=None, actor_ip="", session_id=""):
+        if not self.core.is_on("audit") or not isinstance(action, str) or not action:
+            return
+        entry = {
+            "at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            "action": action[:64], "actor": str(actor or "")[:200], "target": str(target or "")[:300],
+            "details": details, "actor_ip": actor_ip or "", "session_id": session_id or "",
+        }
+        with self.lock:
+            if len(self.queue) >= QUEUE_MAX:
+                return
+            self.queue.append(entry)
+            full = len(self.queue) >= BATCH
+        if full and self.job:
+            self.job.run_now()
+
+    def flush(self):
+        with self.lock:
+            waiting, self.queue = self.queue, []
+        for i in range(0, len(waiting), BATCH):
+            self.core.send("audit", "/events/audit", body={"entries": waiting[i:i + BATCH]})
+
+    def _flush_job(self):
+        self.flush()
+        return FLUSH_EVERY
+
+    def close(self):
+        if self.job:
+            self.job.stop()
+        self.flush()