[FR] - cardano-testnet: machine-readable manifest and status command

[palas]

Internal/External
Internal

Area
cardano-testnet

1. Machine-readable runtime interface (manifest and status)

Problem

When cardano-testnet cardano starts a network it knows every socket path, port, and key location. But it only communicates them as human-oriented log text and an undocumented directory layout.

Programs that start cardano-testnet must therefore scrape the output directory and poll with their own retry loops. Consumers usually build this layer independently: cardano-transaction-lib parses the run directory (their integration doc), the YACD Kubernetes operator wraps the binary, and Tweag's cardano-peras repo wraps it again.

The request is old and still open: #5848 (2024) asks for "more structured output (e.g. JSON) so that we can parse the TMP dir to get the node socket path, etc.".

Proposal

1. Manifest. On successful startup, write <output-dir>/manifest.json: network magic, era, and per node: name, role, socket path, port, config path; plus the funded key files. Document it as a stable interface, so the rest of the directory layout can keep changing freely.
2. Status command. cardano-testnet status --output-dir DIR [--json]: reports ready/synced/tip, exit code 0 only when the chain is producing blocks.

References

#5848 · #6405 (keep-running behavior)

[carbolymer]

Makes sense to me 👍
ad 1) One small caveat: if the user does not specify --output-dir , the output dir is non-deterministic and has to be obtained from the command output, which is not structured atm. Additionally, it would be nice to have schema defined somewhere (e.g jsonschema) for the manifest lying somewhere in the repo.
ad 2) We should spec out status command. What should be the behaviour when one node isn't healthy in multi-node network?

I think this issue should be split into two, because manifest and status command are separate, although one is depending on the other I presume.

[palas]

@carbolymer

ad 1) One small caveat: if the user does not specify --output-dir , the output dir is non-deterministic and has to be obtained from the command output, which is not structured atm. Additionally, it would be nice to have schema defined somewhere (e.g jsonschema) for the manifest lying somewhere in the repo.

I think, when --output-dir is specified, it is always $PWD/testnet. Which is not ideal, because when it fails and you try a second time it fails because the folder already exists, it happens a lot to me. But because there is the option of specifying --output-dir, then if you want predictability in scripts you can just use it, I think that is quite fair to the user.

ad 2) We should spec out status command. What should be the behaviour when one node isn't healthy in multi-node network?

Yes, it is quite open yet, it may be desirable to have a list with information about each node, I'll create sub issues.

[carbolymer]

I think, when --output-dir is specified, it is always $PWD/testnet

You're right. I was reading the argument description, which is misleading now:

  --output-dir DIRECTORY   Directory where to store files, sockets, and so on.
                           It is created if it doesn't exist. If unset, a
                           temporary directory is used.

[palas]

I think, when --output-dir is specified, it is always $PWD/testnet

You're right. I was reading the argument description, which is misleading now:

  --output-dir DIRECTORY   Directory where to store files, sockets, and so on.
                           It is created if it doesn't exist. If unset, a
                           temporary directory is used.

Ah, that is an issue, I will create one