Skip to content

Commit 4ca1e44

Browse files
committed
feat: add deterministic orchestration contract
1 parent 361bb8b commit 4ca1e44

14 files changed

Lines changed: 564 additions & 44 deletions

‎README.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -858,6 +858,11 @@ recovery connection settings, cannot be overridden through `spec.postgres.parame
858858
Diagnostic thresholds and statistics settings are overridable. The tool also owns the
859859
`initdb --pgdata` and `--waldir` paths.
860860

861+
## Orchestrator integration
862+
863+
The normal lifecycle CLI remains human-oriented. Authors of `pg_play`-compatible
864+
orchestrators can use the separate [versioned machine contract](docs/pg_play-integration.md).
865+
861866
## Development
862867

863868
```bash
@@ -894,7 +899,7 @@ python -m build
894899
python -m twine check dist/*
895900
```
896901

897-
A tag matching the package version, for example `v0.1.0`, runs unit and Docker integration
902+
A tag matching the package version, for example `v0.2.0`, runs unit and Docker integration
898903
tests, builds the wheel and source distribution, smoke-tests the installed wheel, and publishes
899904
through PyPI Trusted Publishing. The GitHub `pypi` environment and a PyPI trusted publisher for
900905
`O2eg/pg_stand` and `.github/workflows/publish.yml` must be configured before the first release.

‎docs/pg_play-integration.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# pg_play integration contract
2+
3+
This document is for orchestrator authors. The normal `pg-stand` lifecycle and
4+
observation commands remain the supported human interface.
5+
6+
`pg_stand` supports the hidden `pg_play/component/v1` machine transport:
7+
8+
```bash
9+
pg-stand --machine --request-id stand-001 capabilities
10+
pg-stand --machine --request-id stand-002 --config stand.yaml validate
11+
pg-stand --machine --request-id stand-003 --config stand.yaml plan
12+
```
13+
14+
To plan a generated `pg_configurator` candidate without rewriting the stand
15+
source, pass a JSON parameter mapping through standard input:
16+
17+
```bash
18+
pg-stand --machine --request-id stand-004 \
19+
--config stand.yaml --parameters-json=- plan
20+
```
21+
22+
Topology, TLS, fixed CSV logging, authentication, replication, and diagnostic
23+
preload parameters listed by the public `MANAGED_POSTGRES_PARAMETERS` constant
24+
remain owned by `pg_stand`. An orchestrator must keep those candidate values in
25+
its plan for provenance and pass only the remaining parameter mapping here.
26+
27+
The plan returns its normalized `plan_hash` and a `required_action` of `none`,
28+
`up`, `reload`, `restart`, or `blocked`. A mutating reload/restart must carry
29+
the reviewed hash:
30+
31+
```bash
32+
pg-stand --machine --request-id stand-005 \
33+
--config stand.yaml --parameters-json=- \
34+
apply --restart --plan-hash sha256:...
35+
```
36+
37+
Interactive and unbounded operations are unavailable in machine mode,
38+
including `psql`, `ssh`, `watch`, followed log/event streams, and
39+
`dsn --show-password`. Machine results always redact credentials. Ownership
40+
checks and the normal standalone safety rules still apply.

‎pyproject.toml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "pg-stand"
7-
version = "0.1.0"
7+
version = "0.2.0"
88
description = "Declarative Docker PostgreSQL stand manager"
99
readme = "README.md"
1010
requires-python = ">=3.10"
@@ -55,6 +55,7 @@ Repository = "https://github.com/O2eg/pg_stand"
5555
Issues = "https://github.com/O2eg/pg_stand/issues"
5656

5757
[tool.setuptools]
58+
package-dir = {"" = "src"}
5859
include-package-data = false
5960

6061
[tool.setuptools.packages.find]

‎src/pg_stand/__init__.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
11
"""Declarative PostgreSQL stands managed through the Docker SDK."""
22

3-
__version__ = "0.1.0"
3+
from pg_stand.config import MANAGED_POSTGRES_PARAMETERS
4+
5+
__version__ = "0.2.0"
6+
7+
__all__ = ["MANAGED_POSTGRES_PARAMETERS", "__version__"]

‎src/pg_stand/cli.py‎

Lines changed: 206 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,15 @@
33
from __future__ import annotations
44

55
import argparse
6+
import contextlib
7+
import io
68
import json
79
import re
810
import sys
911
import time
1012
from collections.abc import Sequence
1113
from datetime import datetime, timedelta, timezone
14+
from pathlib import Path
1215
from typing import Any
1316

1417
import docker
@@ -17,7 +20,8 @@
1720
from pg_stand.assets import initialize_project
1821
from pg_stand.cli_parser import _parser
1922
from pg_stand.config import StandConfig, load_config
20-
from pg_stand.errors import DockerRuntimeError, PgStandError
23+
from pg_stand.errors import DockerRuntimeError, PgStandError, PreconditionError
24+
from pg_stand.orchestration import EXIT_CODES, envelope, static_capabilities
2125
from pg_stand.runtime import StandManager, discover_active_stand
2226

2327
_DURATION_RE = re.compile(r"^(?P<value>[0-9]+(?:\.[0-9]+)?)(?P<unit>[smhd])$")
@@ -69,6 +73,40 @@ def _manager(config: StandConfig) -> StandManager:
6973
return StandManager(config, output=lambda message: print(message, file=sys.stderr))
7074

7175

76+
def _postgres_parameters_override(value: str | None) -> dict[str, Any] | None:
77+
if value is None:
78+
return None
79+
try:
80+
if value == "-":
81+
document = json.load(sys.stdin)
82+
else:
83+
document = json.loads(Path(value).expanduser().read_text(encoding="utf-8"))
84+
except (OSError, json.JSONDecodeError) as exc:
85+
raise DockerRuntimeError(f"cannot read PostgreSQL parameters JSON: {exc}") from exc
86+
if not isinstance(document, dict):
87+
raise DockerRuntimeError("PostgreSQL parameters JSON must be an object")
88+
configurator_artifact = "postgresql_conf" in document
89+
if configurator_artifact:
90+
document = document["postgresql_conf"]
91+
elif isinstance(document.get("postgresql"), dict) and "parameters" in document["postgresql"]:
92+
document = document["postgresql"]["parameters"]
93+
if not isinstance(document, dict):
94+
raise DockerRuntimeError("PostgreSQL parameters JSON must resolve to a parameter object")
95+
if configurator_artifact:
96+
document = {
97+
name: _decode_postgresql_conf_value(parameter_value)
98+
for name, parameter_value in document.items()
99+
}
100+
return document
101+
102+
103+
def _decode_postgresql_conf_value(value: Any) -> Any:
104+
"""Convert pg_configurator's rendered string literals to semantic values."""
105+
if isinstance(value, str) and len(value) >= 2 and value.startswith("'") and value.endswith("'"):
106+
return value[1:-1].replace("''", "'")
107+
return value
108+
109+
72110
def _watch(manager: StandManager, args: argparse.Namespace, *, replication_only: bool) -> int:
73111
samples = 0
74112
while args.count == 0 or samples < args.count:
@@ -150,6 +188,13 @@ def _execute(args: argparse.Namespace, config: StandConfig) -> int:
150188
raise DockerRuntimeError(
151189
"apply requires --reload or --restart unless --dry-run is used"
152190
)
191+
if args.plan_hash:
192+
current_plan = manager.plan(requested_mode=requested_mode)
193+
if current_plan["plan_hash"] != args.plan_hash:
194+
raise PreconditionError(
195+
"stale plan: expected "
196+
f"{args.plan_hash}, current plan is {current_plan['plan_hash']}"
197+
)
153198
_emit(
154199
manager.apply(
155200
mode=requested_mode,
@@ -300,9 +345,165 @@ def _execute(args: argparse.Namespace, config: StandConfig) -> int:
300345
return 0
301346

302347

348+
def _command_name(args: argparse.Namespace) -> str:
349+
nested = (
350+
"replication_command",
351+
"storage_command",
352+
"logical_command",
353+
"standby_command",
354+
"node_command",
355+
"image_command",
356+
"cleanup_command",
357+
)
358+
parts = [args.command]
359+
parts.extend(str(value) for name in nested if (value := getattr(args, name, None)))
360+
return " ".join(parts)
361+
362+
363+
def _machine_supported(args: argparse.Namespace) -> bool:
364+
if args.command in {"psql", "ssh", "watch"}:
365+
return False
366+
if args.command == "dsn" and args.show_password:
367+
return False
368+
if args.command in {"logs", "events"} and args.follow:
369+
return False
370+
return True
371+
372+
373+
def _decode_machine_result(output: str) -> Any:
374+
text = output.strip()
375+
if not text:
376+
return None
377+
try:
378+
return json.loads(text)
379+
except json.JSONDecodeError:
380+
return {"stdout": text}
381+
382+
383+
def _machine_status(args: argparse.Namespace, result: Any, exit_code: int) -> str:
384+
if args.command == "plan" and isinstance(result, dict):
385+
if result.get("required_action") == "blocked":
386+
return "blocked"
387+
if exit_code == 0:
388+
return "succeeded"
389+
if exit_code in {1, EXIT_CODES["partial"]}:
390+
return "partial"
391+
return "failed"
392+
393+
394+
def _emit_machine(
395+
args: argparse.Namespace,
396+
*,
397+
result: Any = None,
398+
status: str = "succeeded",
399+
error: dict[str, Any] | None = None,
400+
config: StandConfig | None = None,
401+
) -> None:
402+
artifacts = []
403+
if config is not None:
404+
artifacts.append(
405+
{
406+
"kind": "StandConfiguration",
407+
"schema_version": "pg_stand/v1",
408+
"hash": config.config_hash,
409+
"path": str(config.source),
410+
}
411+
)
412+
_emit(
413+
envelope(
414+
_command_name(args),
415+
status,
416+
request_id=args.request_id,
417+
result=result,
418+
artifacts=artifacts,
419+
error=error,
420+
),
421+
as_json=True,
422+
)
423+
424+
425+
def _run_machine(args: argparse.Namespace) -> int:
426+
if not _machine_supported(args):
427+
_emit_machine(
428+
args,
429+
status="failed",
430+
error={
431+
"code": "unsupported",
432+
"message": (
433+
"interactive or unbounded streaming command is not available in machine mode"
434+
),
435+
},
436+
)
437+
return EXIT_CODES["unsupported"]
438+
439+
config: StandConfig | None = None
440+
try:
441+
args.json = True
442+
output = io.StringIO()
443+
with contextlib.redirect_stdout(output):
444+
if args.command == "active":
445+
result = discover_active_stand()
446+
exit_code = 0 if result["active"] else 1
447+
print(json.dumps(result))
448+
elif args.command == "init":
449+
result = initialize_project(args.directory, force=args.force)
450+
exit_code = 0
451+
print(json.dumps(result))
452+
elif args.command == "capabilities" and args.config is None:
453+
result = static_capabilities()
454+
exit_code = 0
455+
print(json.dumps(result))
456+
else:
457+
if args.config is None:
458+
raise DockerRuntimeError(f"--config is required for {args.command}")
459+
config = load_config(
460+
args.config,
461+
postgres_version=args.postgres_version,
462+
tls_enabled=args.tls,
463+
postgres_parameters=_postgres_parameters_override(args.parameters_json),
464+
)
465+
exit_code = _execute(args, config)
466+
result = _decode_machine_result(output.getvalue())
467+
if args.command == "capabilities" and config is not None and isinstance(result, dict):
468+
result = {"contract": static_capabilities(), "target": result}
469+
status = _machine_status(args, result, exit_code)
470+
_emit_machine(args, result=result, status=status, config=config)
471+
if status == "blocked":
472+
return EXIT_CODES["precondition_failed"]
473+
if exit_code == 1:
474+
return EXIT_CODES["partial"]
475+
return exit_code
476+
except PreconditionError as exc:
477+
_emit_machine(
478+
args,
479+
status="blocked",
480+
error={"code": "precondition_failed", "message": str(exc)},
481+
config=config,
482+
)
483+
return EXIT_CODES["precondition_failed"]
484+
except (PgStandError, docker.errors.DockerException) as exc:
485+
_emit_machine(
486+
args,
487+
status="failed",
488+
error={"code": "execution_error", "message": str(exc)},
489+
config=config,
490+
)
491+
return EXIT_CODES["execution_error"]
492+
except KeyboardInterrupt:
493+
_emit_machine(
494+
args,
495+
status="cancelled",
496+
error={"code": "cancelled", "message": "interrupted"},
497+
config=config,
498+
)
499+
return EXIT_CODES["cancelled"]
500+
501+
303502
def main(argv: Sequence[str] | None = None) -> int:
304503
parser = _parser()
305504
args = parser.parse_args(argv)
505+
if args.machine:
506+
return _run_machine(args)
306507
try:
307508
if args.command == "active":
308509
result = discover_active_stand()
@@ -314,12 +515,16 @@ def main(argv: Sequence[str] | None = None) -> int:
314515
as_json=args.json,
315516
)
316517
return 0
518+
if args.command == "capabilities" and args.config is None:
519+
_emit(static_capabilities(), as_json=args.json)
520+
return 0
317521
if args.config is None:
318522
raise DockerRuntimeError(f"--config is required for {args.command}")
319523
config = load_config(
320524
args.config,
321525
postgres_version=args.postgres_version,
322526
tls_enabled=args.tls,
527+
postgres_parameters=_postgres_parameters_override(args.parameters_json),
323528
)
324529
return _execute(args, config)
325530
except (PgStandError, docker.errors.DockerException) as exc:

‎src/pg_stand/cli_parser.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,19 @@ def _parser() -> argparse.ArgumentParser:
7474
help="override spec.postgres.tls.enabled for this command",
7575
)
7676
parser.add_argument("--json", action="store_true", help="print machine-readable JSON")
77+
parser.add_argument(
78+
"--machine",
79+
action="store_true",
80+
help=argparse.SUPPRESS,
81+
)
82+
parser.add_argument(
83+
"--request-id",
84+
help=argparse.SUPPRESS,
85+
)
86+
parser.add_argument(
87+
"--parameters-json",
88+
help=argparse.SUPPRESS,
89+
)
7790

7891
commands = parser.add_subparsers(dest="command", required=True)
7992
commands.add_parser("active", help="discover the active pg-stand lease without a config")
@@ -153,6 +166,10 @@ def _parser() -> argparse.ArgumentParser:
153166
apply_config.add_argument(
154167
"--dry-run", action="store_true", help="show the plan without changing anything"
155168
)
169+
apply_config.add_argument(
170+
"--plan-hash",
171+
help="apply only if the current plan still matches this hash",
172+
)
156173
apply_config.add_argument(
157174
"--timeout", type=_positive_float, default=180.0, help="readiness timeout in seconds"
158175
)

0 commit comments

Comments
 (0)