"""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]