xflog 1.0.0__py3-none-any.whl

xflog/__init__.py

@@ -0,0 +1,16 @@
+"""XFlog — X Follower Log."""
+
+from .config import CoreConfig
+from .errors import RuntimeBusyError, SetupError
+from .interactions.history import ThreadOptions
+from .runtime import Runtime
+from .tracking.transport import ProviderError
+
+__all__ = [
+    "CoreConfig",
+    "ProviderError",
+    "Runtime",
+    "RuntimeBusyError",
+    "SetupError",
+    "ThreadOptions",
+]

xflog/__main__.py

@@ -0,0 +1,69 @@
+import argparse
+import asyncio
+import logging
+
+import httpx
+
+from .config import Config, CoreConfig
+from .errors import SetupError
+from .tracking.transport import ProviderError, XClient, provider_http
+
+
+async def lookup_user_id(handle: str | None) -> str:
+    config = CoreConfig.from_env()
+    async with provider_http() as http:
+        return await XClient(config, http).lookup_user_id(handle)
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="XFlog: run the UI or look up an X account ID.")
+    commands = parser.add_subparsers(dest="command")
+    lookup = commands.add_parser(
+        "user-id", help="Look up an account ID (one X read; X charges may apply)."
+    )
+    target = lookup.add_mutually_exclusive_group(required=True)
+    target.add_argument("handle", nargs="?", help="@handle, using X_APP_BEARER_TOKEN")
+    target.add_argument("--me", action="store_true", help="Use X_USER_ACCESS_TOKEN (OAuth 2.0)")
+    args = parser.parse_args(argv)
+    if args.command == "user-id":
+        try:
+            print(asyncio.run(lookup_user_id(args.handle)))
+        except (SetupError, ValueError) as error:
+            raise SystemExit(str(error)) from None
+        except ProviderError as error:
+            raise SystemExit(
+                f"X user lookup failed (HTTP {error.status}). "
+                "Check the account, token permissions, API access and credits."
+            ) from None
+        except httpx.HTTPError:
+            raise SystemExit("Could not reach X. Check your connection and try again.") from None
+        return
+    serve()
+
+
+def serve() -> None:
+    try:
+        import uvicorn
+
+        from .app import create_app
+    except ModuleNotFoundError as error:
+        if error.name not in {"uvicorn", "fastapi", "gradio"}:
+            raise
+        raise SystemExit(
+            'The browser UI is optional. Install it with: pip install "xflog[ui]" '
+            "(or use uv pip install with the same argument)."
+        ) from None
+    config = Config.from_env()
+    logging.getLogger("httpx").setLevel(logging.CRITICAL)
+    logging.getLogger("httpcore").setLevel(logging.CRITICAL)
+    uvicorn.run(
+        create_app(config),
+        host=config.host,
+        port=config.port,
+        access_log=False,
+        proxy_headers=False,
+    )
+
+
+if __name__ == "__main__":
+    main()

xflog/app.py

@@ -0,0 +1,339 @@
+import asyncio
+import secrets
+import sqlite3
+import time
+from urllib.parse import urlsplit
+
+import httpx
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+from fastapi.security import HTTPBasic
+from fastapi.staticfiles import StaticFiles
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from . import audience_groups
+from .config import ASSETS, Config
+from .errors import SetupError
+from .history.demo import demo_activity, demo_history
+from .history.demo import encounter_context as demo_encounter_context
+from .history.filters import valid_filters
+from .history.summary import PERIODS, SUBJECT_TYPES, activity_window, readings
+from .history.timeline import Timeline, decode_cursor
+from .interactions import TYPES, catalog
+from .interactions.history import ThreadOptions
+from .profile_names import ProfileNames
+from .runtime import Runtime
+from .tracking.collector import DEFAULT_SELECTION
+from .tracking.transport import ProviderError
+from .web.models import (
+    AudiencePreferences,
+    FollowChange,
+    FollowTarget,
+    Selection,
+    StartRequest,
+    ThreadRequest,
+)
+from .web.ui import mount_ui as mount_browser_ui
+
+
+def create_app(config: Config | None = None, *, transport=None, mount_ui=True):
+    config = config or Config.from_env()
+    runtime = Runtime(config, transport=transport)
+    store, collector = runtime.store, runtime.collector
+    timeline = Timeline(store)
+    profile_names = ProfileNames(store, runtime.client)
+    follow_actions, interactions = runtime.follow_actions, runtime.interactions
+    sessions = {}
+    controls = asyncio.Lock()
+
+    app = FastAPI(lifespan=runtime.lifespan, docs_url=None, redoc_url=None, openapi_url=None)
+    app.state.store, app.state.collector = store, collector
+    app.state.client, app.state.sessions = runtime.client, sessions
+    app.state.runtime = runtime
+    app.state.follow_actions = follow_actions
+    app.state.interactions = interactions
+    app.add_middleware(TrustedHostMiddleware, allowed_hosts=[urlsplit(config.origin).hostname])
+    basic_auth = HTTPBasic(auto_error=False)
+
+    @app.middleware("http")
+    async def instance_security(request: Request, call_next):
+        if request.headers.get("host") != urlsplit(config.origin).netloc:
+            return JSONResponse({"detail": "Use the configured XFlog address."}, status_code=403)
+        if request.url.path != "/healthz" and config.admin_password:
+            try:
+                credentials = await basic_auth(request)
+            except HTTPException:
+                credentials = None
+            if not credentials or not (
+                secrets.compare_digest(credentials.username.encode(), b"xflog")
+                and secrets.compare_digest(
+                    credentials.password.encode(), config.admin_password.encode()
+                )
+            ):
+                return JSONResponse(
+                    {"detail": "Instance authentication required."},
+                    status_code=401,
+                    headers={
+                        "WWW-Authenticate": 'Basic realm="XFlog", charset="UTF-8"',
+                        "Cache-Control": "no-store",
+                    },
+                )
+        if request.headers.get("sec-fetch-site") in {"cross-site", "same-site"}:
+            return JSONResponse(
+                {"detail": "Open XFlog directly on its configured address."},
+                status_code=403,
+            )
+        session = request.cookies.get("xflog_session")
+        now = time.monotonic()
+        fresh = False
+        if request.url.path == "/" and request.method == "GET":
+            for key in [key for key, value in sessions.items() if value["expires"] < now]:
+                sessions.pop(key)
+            if session not in sessions:
+                if len(sessions) >= 100:
+                    return JSONResponse(
+                        {"detail": "Too many local browser sessions."}, status_code=429
+                    )
+                session = secrets.token_urlsafe(32)
+                sessions[session] = {
+                    "csrf": secrets.token_urlsafe(32),
+                    "expires": now + 86400,
+                }
+                fresh = True
+        protected = request.url.path.startswith("/api/")
+        current = sessions.get(session)
+        if protected and (not current or current["expires"] < now):
+            return JSONResponse(
+                {"detail": "Reload XFlog to begin a local session."}, status_code=401
+            )
+        if protected and request.method not in {"GET", "HEAD"}:
+            if request.headers.get("origin") != config.origin or not secrets.compare_digest(
+                request.headers.get("x-xflog-csrf", ""), current["csrf"]
+            ):
+                return JSONResponse(
+                    {"detail": "Request could not be verified. Reload XFlog."},
+                    status_code=403,
+                )
+        request.state.session = session
+        response = await call_next(request)
+        if fresh:
+            response.set_cookie(
+                "xflog_session",
+                session,
+                httponly=True,
+                secure=config.secure,
+                samesite="lax",
+                max_age=86400,
+            )
+        response.headers.update(
+            {
+                "Cache-Control": "no-store",
+                "Referrer-Policy": "no-referrer",
+                "X-Content-Type-Options": "nosniff",
+                "X-Frame-Options": "DENY",
+            }
+        )
+        return response
+
+    @app.exception_handler(SetupError)
+    @app.exception_handler(ProviderError)
+    async def known_error(request, error):
+        return JSONResponse({"detail": str(error)}, status_code=409)
+
+    @app.exception_handler(sqlite3.Error)
+    @app.exception_handler(OSError)
+    async def database_error(request, error):
+        return JSONResponse(
+            {"detail": "Local database unavailable. Check disk space and file access."},
+            status_code=503,
+        )
+
+    @app.exception_handler(httpx.HTTPError)
+    async def network_error(request, error):
+        return JSONResponse(
+            {"detail": "Could not reach X. Check your connection and retry."},
+            status_code=502,
+        )
+
+    @app.get("/api/status")
+    async def status(request: Request):
+        account = await store.setting("account")
+        selection = await store.setting("selection", DEFAULT_SELECTION)
+        return {
+            "account": account,
+            "connected": collector.connected,
+            "state": collector.state,
+            "message": collector.message,
+            "selection": selection,
+            "missing_settings": runtime.config.missing_settings(selection),
+            "setup_message": runtime.identity_error or runtime.config.setup_message(selection),
+            "environment_file": config.environment_file,
+            "preference_warning": collector.preference_warning,
+            "profile_warning": await store.setting("profile_warning", "")
+            if selection.get("profile_names")
+            else "",
+            "tracking": await store.setting("tracking", False),
+            "counts": await store.summary(account["id"]) if account else {},
+            "gaps": await store.gaps(account["id"]) if account else [],
+            "cleanup_warning": await store.setting("cleanup_warning", ""),
+            "csrf": sessions[request.state.session]["csrf"],
+            "notification_sequence": collector.notifications,
+            "timeline_revision": await timeline.revision(account["id"]) if account else "0:0",
+            "audience_groups": audience_groups.catalog(await store.setting("audience_groups", {})),
+            "follow_actions": await follow_actions.status(),
+            "interaction_types": catalog(),
+        }
+
+    @app.get("/api/activity-summary")
+    async def activity_summary(period: str = "24h", subject: str = "followers", demo: bool = False):
+        if period not in PERIODS or subject not in SUBJECT_TYPES:
+            raise HTTPException(422, "Invalid activity period or audience.")
+        if demo:
+            return demo_activity(period, subject)
+        window = activity_window(period)
+        account = await store.setting("account")
+        counts = await store.activity_counts(account["id"], window, subject) if account else {}
+        return {**readings(counts, window, subject), "synthetic": False}
+
+    @app.get("/api/timeline")
+    async def timeline_history(kind: str = "all", subject: str = "followers", before: str = "0"):
+        try:
+            decode_cursor(before)
+        except ValueError:
+            raise HTTPException(422, "Invalid timeline cursor.") from None
+        if not valid_filters(kind, subject, 0):
+            raise HTTPException(422, "Invalid timeline filter.")
+        account = await store.setting("account")
+        if not account:
+            return {"events": [], "next": None}
+        result = await timeline.history(
+            account["id"], {"kind": kind, "subject": subject, "before": before}
+        )
+        if await profile_names.ensure(result["events"]):
+            result = await timeline.history(
+                account["id"], {"kind": kind, "subject": subject, "before": before}
+            )
+        groups = await store.setting("audience_groups", {})
+        result["events"] = await audience_groups.decorate_history(
+            result["events"], groups, timeline.encounter_context
+        )
+        return result
+
+    @app.get("/api/events")
+    async def history(kind: str = "all", subject: str = "followers", before: int = 0):
+        if not valid_filters(kind, subject, before):
+            raise HTTPException(422, "Invalid history filter.")
+        account = await store.setting("account")
+        if not account:
+            return {"events": [], "next": None}
+        result = await store.history(
+            account["id"], {"kind": kind, "subject": subject, "before": before}
+        )
+        groups = await store.setting("audience_groups", {})
+        result["events"] = await audience_groups.decorate_history(
+            result["events"], groups, store.encounter_context
+        )
+        return result
+
+    @app.get("/api/demo")
+    async def demo(kind: str = "all", subject: str = "followers", before: int = 0):
+        if not valid_filters(kind, subject, before):
+            raise HTTPException(422, "Invalid demo filter.")
+        result = demo_history({"kind": kind, "subject": subject, "before": before})
+        groups = await store.setting("audience_groups", {})
+        result["events"] = await audience_groups.decorate_history(
+            result["events"], groups, demo_encounter_context
+        )
+        return result
+
+    @app.post("/api/audience-groups")
+    async def save_audience_groups(settings: AudiencePreferences):
+        if settings.enabled.keys() - audience_groups.MODULES.keys():
+            raise HTTPException(422, "Unknown audience group.")
+        async with controls:
+            previous = audience_groups.preferences(await store.setting("audience_groups", {}))
+            enabled = {**previous, **settings.enabled}
+            await store.save_setting("audience_groups", enabled)
+        return {"audience_groups": audience_groups.catalog(enabled)}
+
+    @app.post("/api/preferences")
+    async def preferences(selection: Selection):
+        async with interactions.lock:
+            previous = await store.setting("selection", DEFAULT_SELECTION)
+            follow_setting = (
+                selection.follow_actions if "follow_actions" in selection.model_fields_set else None
+            )
+            if follow_setting is not None:
+                follow_actions.validate_setting(follow_setting)
+            values = selection.model_dump(exclude={"follow_actions", "interactions"})
+            if selection.interactions is not None:
+                if selection.interactions.keys() - TYPES.keys():
+                    raise HTTPException(422, "Unknown interaction type.")
+                values["interactions"] = selection.interactions
+            else:
+                if "interactions" in previous:
+                    values["interactions"] = previous["interactions"]
+            interactions.validate_selection(values)
+            result = await collector.save_preferences(values)
+            if result["saved"] and selection.profile_names and not previous.get("profile_names"):
+                await profile_names.retry_unresolved()
+            if result["saved"] and follow_setting is not None:
+                await follow_actions.configure(follow_setting)
+            return result
+
+    @app.post("/api/follow-actions/relationship")
+    async def follow_relationship(target: FollowTarget):
+        if target.demo:
+            raise SetupError("Follow actions are unavailable in the offline demo.")
+        return await follow_actions.relationship(target.event_id)
+
+    @app.post("/api/follow-actions")
+    async def change_follow(target: FollowChange):
+        if target.demo:
+            raise SetupError("Follow actions are unavailable in the offline demo.")
+        return await follow_actions.change(target.event_id, target.following)
+
+    @app.get("/api/interactions")
+    async def person_interactions(event_id: str, before: int = 0, demo: bool = False):
+        if not 0 <= before <= 9223372036854775807 or not 1 <= len(event_id) <= 200:
+            raise HTTPException(422, "Invalid interaction query.")
+        if demo:
+            return {"interactions": [], "next": None}
+        return await interactions.history(event_id, before)
+
+    @app.post("/api/interactions/thread")
+    async def thread_snapshot(body: ThreadRequest):
+        if body.demo:
+            raise SetupError("Thread loading is unavailable in the offline demo.")
+        options = ThreadOptions(**body.model_dump(exclude={"event_id", "demo"}))
+        return await interactions.thread(body.event_id, options)
+
+    @app.post("/api/start")
+    async def start(body: StartRequest):
+        if not body.accepted_costs:
+            raise HTTPException(422, "Review billing and explicitly accept before starting.")
+        async with controls:
+            await collector.start()
+        return {"started": True}
+
+    @app.post("/api/stop")
+    async def stop():
+        async with controls:
+            await collector.stop()
+        return {"stopped": True}
+
+    app.mount("/static/xf", StaticFiles(directory=ASSETS), name="assets")
+
+    @app.get("/healthz")
+    async def health():
+        return {"ok": True}
+
+    if mount_ui:
+        app = mount_browser_ui(app, config)
+    else:
+
+        @app.get("/")
+        async def root():
+            return {"app": "XFlog"}
+
+    return app

xflog/assets/FONT-LICENSE.txt

@@ -0,0 +1,93 @@
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.