Source code for fleetmesh_node.storage.locator

"""Where each of the node's stores lives, decided once from config.

Every store site in the tree reads the same two things: a directory and a
logical name, joined into `<directory>/<name>.sqlite`. That join is the only
reason the tree is tied to SQLite now that the dialect layer exists, so it is
the thing to replace - not with a flag threaded through fourteen files, but
with one object that answers "where does the store called `grants` live" and
is built once from the node's configuration.

    loc = Locator.from_config(directory)                  # the default
    loc = Locator.from_config(directory, url='postgresql://...')
    store = loc.open(grants.GrantStore, 'grants')

On SQLite that is the same path the site computed before, so the default node
is byte-for-byte unchanged. On PostgreSQL every store gets the same URL: one
node per database is settled (docs/storage-backends.md section 10), the forty-
four table names do not collide, and the schema version is already keyed by
store name rather than by database - the defect that taught us so is recorded
at postgres.py:218.

One dialect instance is shared by every store it opens. `PostgresDialect`
learns each table's columns and primary key from the DDL passing through
`sql()`, so sharing means the reflection is learned once rather than fourteen
times, and the methods that use a connection take it as an argument.

A backend is named by URL scheme, and an unknown one is refused by name
rather than quietly becoming a filename.
"""
from __future__ import annotations

import os
from typing import Any, Callable, Optional, TypedDict

from .dialect import Dialect, SqliteDialect

SQLITE_SUFFIX = '.sqlite'
POSTGRES_SCHEMES = ('postgresql://', 'postgres://')


class _Backend(TypedDict):
    backend: str


[docs]class StorageBackend(_Backend, total=False): """The backend as `meshnode health` reports it. A named record rather than a loose mapping, for the same reason `StoreLease` is one: check-dicts.py holds this tree to typing what it returns, and a row an operator reads by field name is the case that rule exists for. Exactly one of `directory` and `server` is present - which one is the answer being reported. """ directory: str server: str owner: str
[docs]class Locator: """The node's storage target. Build it with `from_config`."""
[docs] def __init__(self, directory: str, dialect: Dialect, url: Optional[str] = None, owner: Optional[str] = None) -> None: self.directory: str = directory self.dialect: Dialect = dialect self.url: Optional[str] = url self.owner: Optional[str] = owner
# ---- construction -----------------------------------------------------
[docs] @classmethod def from_config(cls, directory: str, url: Optional[str] = None, owner: Optional[str] = None) -> 'Locator': """The locator a node's config asks for. No URL is the default and needs nothing of the operator. A URL names its backend by scheme; anything else is a configuration error and is reported as one, because treating it as a path would produce a node that silently ran on SQLite while an operator believed otherwise. `owner` is the node's identity for the ownership lease. It is what makes one node per database enforced rather than assumed (docs/storage-backends.md section 5a): `BaseStore` claims a lease only when it is given an owner, so a locator without one opens stores that claim nothing. On a server every store shares the database and therefore shares the one `fleetmesh_owner` row, so the first store to open claims the database for this node and a second node is refused. """ if not url: return cls(directory, SqliteDialect(), owner=owner) if url.startswith(POSTGRES_SCHEMES): from .postgres import PostgresDialect # noqa: PLC0415 (optional) return cls(directory, PostgresDialect(), url=url, owner=owner) raise ValueError( 'unknown storage URL scheme: %r - expected one of %s, or no URL for the ' 'SQLite default' % (url.split('://')[0], ', '.join(POSTGRES_SCHEMES)))
# ---- use --------------------------------------------------------------
[docs] def target(self, name: str) -> str: """The connection target for the store called `name`. A file per store on SQLite. One database for all of them on a server, which is what "one node per database" means. """ if self.url is not None: return self.url return os.path.join(self.directory, name + SQLITE_SUFFIX)
[docs] def open(self, store_cls: Callable[..., Any], name: str, **kw: Any) -> Any: """Construct a store of `store_cls` where `name` belongs. `kw` is passed through untouched, so a store with its own arguments - `ttl_seconds`, `readonly` - keeps them, and a caller naming `owner` itself wins over the locator's. """ if self.owner is not None: kw.setdefault('owner', self.owner) return store_cls(self.target(name), dialect=self.dialect, **kw)
# ---- what an operator is shown ----------------------------------------
[docs] def describe(self) -> StorageBackend: """The backend, for `meshnode health`. Which backend is live is otherwise invisible until something breaks, and a node believed to be on PostgreSQL while running on SQLite is exactly the failure this reports. The URL is reduced to host and database: a connection string carries a password. """ out: StorageBackend = {'backend': self.dialect.name} if self.url is None: out['directory'] = self.directory else: out['server'] = redact(self.url) if self.owner is not None: out['owner'] = self.owner return out
[docs]def redact(url: str) -> str: """`postgresql://user:pw@host:5432/db` -> `host:5432/db`. A password in a connection string must not reach a log, a health block or a receipt, and the part an operator needs to recognise the server is the part after the credentials. """ rest = url.split('://', 1)[1] if '://' in url else url if '@' in rest: rest = rest.rsplit('@', 1)[1] return rest.split('?', 1)[0]