|
| 1 | +"""External PostgreSQL runtime helpers for Shellbrain init.""" |
| 2 | + |
| 3 | +from __future__ import annotations |
| 4 | + |
| 5 | +import importlib.metadata |
| 6 | +import secrets |
| 7 | + |
| 8 | +import psycopg |
| 9 | +from psycopg import sql |
| 10 | +from sqlalchemy.engine import make_url |
| 11 | + |
| 12 | +from app.boot.config import get_config_provider |
| 13 | +from app.boot.home import get_machine_backups_dir, get_machine_models_dir |
| 14 | +from app.periphery.admin.init_errors import InitConflictError |
| 15 | +from app.periphery.admin.instance_guard import dsn_fingerprint, ensure_instance_metadata |
| 16 | +from app.periphery.admin.machine_state import ( |
| 17 | + BOOTSTRAP_STATE_PROVISIONING, |
| 18 | + BOOTSTRAP_VERSION, |
| 19 | + CONFIG_VERSION, |
| 20 | + BackupState, |
| 21 | + DatabaseState, |
| 22 | + EmbeddingRuntimeState, |
| 23 | + MachineConfig, |
| 24 | + RUNTIME_MODE_EXTERNAL_POSTGRES, |
| 25 | +) |
| 26 | +from app.periphery.admin.privileges import reconcile_app_role_privileges |
| 27 | + |
| 28 | + |
| 29 | +DEFAULT_EXTERNAL_APP_USER = "shellbrain_app" |
| 30 | + |
| 31 | + |
| 32 | +def build_fresh_machine_config(*, admin_dsn: str) -> MachineConfig: |
| 33 | + """Construct one fresh machine config for external PostgreSQL mode.""" |
| 34 | + |
| 35 | + runtime = get_config_provider().get_runtime() |
| 36 | + embeddings = runtime.get("embeddings") |
| 37 | + if not isinstance(embeddings, dict): |
| 38 | + raise RuntimeError("runtime.embeddings must be configured") |
| 39 | + app_dsn = _provision_external_app_role(admin_dsn=admin_dsn) |
| 40 | + instance_id = dsn_fingerprint(admin_dsn) |
| 41 | + backend_version = _sentence_transformers_version() |
| 42 | + return MachineConfig( |
| 43 | + config_version=CONFIG_VERSION, |
| 44 | + bootstrap_version=BOOTSTRAP_VERSION, |
| 45 | + instance_id=instance_id, |
| 46 | + runtime_mode=RUNTIME_MODE_EXTERNAL_POSTGRES, |
| 47 | + bootstrap_state=BOOTSTRAP_STATE_PROVISIONING, |
| 48 | + current_step="bootstrap", |
| 49 | + last_error=None, |
| 50 | + database=DatabaseState(app_dsn=app_dsn, admin_dsn=admin_dsn), |
| 51 | + managed=None, |
| 52 | + backups=BackupState(root=str(get_machine_backups_dir()), mirror_root=None), |
| 53 | + embeddings=EmbeddingRuntimeState( |
| 54 | + provider=str(embeddings.get("provider") or "sentence_transformers"), |
| 55 | + model=str(embeddings.get("model") or "all-MiniLM-L6-v2"), |
| 56 | + model_revision=None, |
| 57 | + backend_version=backend_version, |
| 58 | + cache_path=str(get_machine_models_dir()), |
| 59 | + readiness_state="pending", |
| 60 | + last_error=None, |
| 61 | + ), |
| 62 | + ) |
| 63 | + |
| 64 | + |
| 65 | +def reconcile_database(config: MachineConfig) -> tuple[bool, MachineConfig]: |
| 66 | + """Validate one external PostgreSQL database and reconcile the Shellbrain app role.""" |
| 67 | + |
| 68 | + if config.runtime_mode != RUNTIME_MODE_EXTERNAL_POSTGRES: |
| 69 | + raise InitConflictError("External runtime reconciliation requires external_postgres mode.") |
| 70 | + _validate_external_admin_dsn(config.database.admin_dsn) |
| 71 | + app_dsn = _provision_external_app_role( |
| 72 | + admin_dsn=config.database.admin_dsn, |
| 73 | + existing_app_dsn=config.database.app_dsn, |
| 74 | + ) |
| 75 | + ensure_instance_metadata( |
| 76 | + config.database.admin_dsn, |
| 77 | + instance_mode="live", |
| 78 | + created_by="app.init", |
| 79 | + notes="External PostgreSQL Shellbrain instance", |
| 80 | + ) |
| 81 | + if app_dsn == config.database.app_dsn: |
| 82 | + return False, config |
| 83 | + updated = MachineConfig( |
| 84 | + config_version=config.config_version, |
| 85 | + bootstrap_version=config.bootstrap_version, |
| 86 | + instance_id=config.instance_id, |
| 87 | + runtime_mode=config.runtime_mode, |
| 88 | + bootstrap_state=config.bootstrap_state, |
| 89 | + current_step=config.current_step, |
| 90 | + last_error=config.last_error, |
| 91 | + database=DatabaseState(app_dsn=app_dsn, admin_dsn=config.database.admin_dsn), |
| 92 | + managed=config.managed, |
| 93 | + backups=config.backups, |
| 94 | + embeddings=config.embeddings, |
| 95 | + ) |
| 96 | + return True, updated |
| 97 | + |
| 98 | + |
| 99 | +def inspect_runtime(*, admin_dsn: str) -> list[str]: |
| 100 | + """Return best-effort warnings for one external PostgreSQL runtime.""" |
| 101 | + |
| 102 | + warnings: list[str] = [] |
| 103 | + try: |
| 104 | + _validate_external_admin_dsn(admin_dsn) |
| 105 | + except InitConflictError as exc: |
| 106 | + warnings.append(str(exc)) |
| 107 | + return warnings |
| 108 | + |
| 109 | + |
| 110 | +def _validate_external_admin_dsn(admin_dsn: str) -> None: |
| 111 | + """Verify the external admin DSN reaches PostgreSQL with pgvector available.""" |
| 112 | + |
| 113 | + raw_admin_dsn = admin_dsn.replace("+psycopg", "") |
| 114 | + try: |
| 115 | + with psycopg.connect(raw_admin_dsn, autocommit=True) as conn: |
| 116 | + with conn.cursor() as cur: |
| 117 | + cur.execute("SELECT version()") |
| 118 | + version_row = cur.fetchone() |
| 119 | + if version_row is None or "PostgreSQL" not in str(version_row[0]): |
| 120 | + raise InitConflictError("External database must be PostgreSQL.") |
| 121 | + try: |
| 122 | + cur.execute("CREATE EXTENSION IF NOT EXISTS vector") |
| 123 | + except psycopg.Error as exc: |
| 124 | + raise InitConflictError( |
| 125 | + "External PostgreSQL database must have pgvector available to install or already installed." |
| 126 | + ) from exc |
| 127 | + cur.execute("SELECT 1 FROM pg_extension WHERE extname = 'vector'") |
| 128 | + if cur.fetchone() is None: |
| 129 | + raise InitConflictError( |
| 130 | + "External PostgreSQL database must have the pgvector extension installed." |
| 131 | + ) |
| 132 | + except InitConflictError: |
| 133 | + raise |
| 134 | + except psycopg.Error as exc: |
| 135 | + raise InitConflictError(f"Could not connect to the external PostgreSQL admin DSN: {exc}") from exc |
| 136 | + |
| 137 | + |
| 138 | +def _provision_external_app_role(*, admin_dsn: str, existing_app_dsn: str | None = None) -> str: |
| 139 | + """Create or repair the dedicated Shellbrain app role for one external database.""" |
| 140 | + |
| 141 | + app_user = DEFAULT_EXTERNAL_APP_USER |
| 142 | + app_password = None |
| 143 | + if existing_app_dsn: |
| 144 | + app_url = make_url(existing_app_dsn) |
| 145 | + app_user = app_url.username or DEFAULT_EXTERNAL_APP_USER |
| 146 | + app_password = app_url.password |
| 147 | + if not app_password: |
| 148 | + app_password = secrets.token_hex(16) |
| 149 | + app_dsn = _app_dsn_from_admin_dsn(admin_dsn=admin_dsn, app_user=app_user, app_password=app_password) |
| 150 | + raw_admin_dsn = admin_dsn.replace("+psycopg", "") |
| 151 | + database_name = make_url(admin_dsn).database |
| 152 | + if not database_name: |
| 153 | + raise InitConflictError("External PostgreSQL admin DSN must include a database name.") |
| 154 | + try: |
| 155 | + with psycopg.connect(raw_admin_dsn, autocommit=True) as conn: |
| 156 | + with conn.cursor() as cur: |
| 157 | + cur.execute("SELECT 1 FROM pg_roles WHERE rolname = %s", (app_user,)) |
| 158 | + if cur.fetchone() is None: |
| 159 | + cur.execute( |
| 160 | + sql.SQL("CREATE ROLE {} LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE PASSWORD {}").format( |
| 161 | + sql.Identifier(app_user), |
| 162 | + sql.Literal(app_password), |
| 163 | + ), |
| 164 | + ) |
| 165 | + else: |
| 166 | + cur.execute( |
| 167 | + sql.SQL("ALTER ROLE {} WITH PASSWORD {}").format( |
| 168 | + sql.Identifier(app_user), |
| 169 | + sql.Literal(app_password), |
| 170 | + ), |
| 171 | + ) |
| 172 | + cur.execute( |
| 173 | + sql.SQL("GRANT CONNECT ON DATABASE {} TO {}").format( |
| 174 | + sql.Identifier(database_name), |
| 175 | + sql.Identifier(app_user), |
| 176 | + ) |
| 177 | + ) |
| 178 | + except psycopg.Error as exc: |
| 179 | + raise InitConflictError(f"Could not provision the external Shellbrain app role: {exc}") from exc |
| 180 | + reconcile_app_role_privileges(admin_dsn=admin_dsn, app_dsn=app_dsn) |
| 181 | + return app_dsn |
| 182 | + |
| 183 | + |
| 184 | +def _app_dsn_from_admin_dsn(*, admin_dsn: str, app_user: str, app_password: str) -> str: |
| 185 | + """Build one Shellbrain app DSN from the external admin DSN shape.""" |
| 186 | + |
| 187 | + url = make_url(admin_dsn) |
| 188 | + return str(url.set(username=app_user, password=app_password)) |
| 189 | + |
| 190 | + |
| 191 | +def _sentence_transformers_version() -> str | None: |
| 192 | + """Return the installed sentence-transformers version when present.""" |
| 193 | + |
| 194 | + try: |
| 195 | + return importlib.metadata.version("sentence-transformers") |
| 196 | + except importlib.metadata.PackageNotFoundError: |
| 197 | + return None |
0 commit comments