common/commands: add a command builder package

[phlogistonjohn]

A generic command builder API that lets one construct commands dynamically in a manner similar to what the ceph command line tool does.

This is actually something I had planned on doing since at least 5 years now. While we did have some documenation on how to accomplish this in the hints.md file, I don't think many people were reading it and it was a bit "thin". So after the umpteenth time I said or wrote something like, "yes you can replicate nearly all ceph commands using go-ceph" or "if you make your own JSON and call the right api you can do that". I finally sat down and implemented a good chunk of it... including a fairly extensive doc.go explaining the background of the package.

So now we have both code that one can use directly and it can serve as an example for folks who just might want to get started doing their own "admin" package for some topic.

Checklist

• Added tests for features and functional changes
• Public functions and types are documented
• Standard formatting is applied to Go code
• Is this a new API? Added a new file that begins with //go:build ceph_preview
• Ran make api-update to record new APIs

New or infrequent contributors may want to review the go-ceph Developer's Guide including the section on how we track API Status and the API Stability Plan.

The go-ceph project uses mergify. View the mergify command guide for information on how to interact with mergify. Add a comment with @Mergifyio rebase to rebase your PR when github indicates that the PR is out of date with the base branch.

[phlogistonjohn]

🥣

[anoopcs9]

I only have few minor comments.

Should we go for a Show() method on Description to display details for a command once a match is found using Match() or Find()?

[phlogistonjohn]

Should we go for a Show() method on Description to display details for a command once a match is found using Match() or Find()?

What would it return?

[anoopcs9]

Should we go for a Show() method on Description to display details for a command once a match is found using Match() or Find()?

What would it return?

Either a slice of strings or a map[string]string. The basic idea is to provide a way to query the expected format and values for the command in question while trying to use Apply() on an already created Builder type.

[phlogistonjohn]

Either a slice of strings or a map[string]string. The basic idea is to provide a way to query the expected format and values for the command in question while trying to use Apply() on an already created Builder type.

So like Variables but returns a slice of the SignatureVar.name instead of the whole SignatureVar?

[anoopcs9]

Either a slice of strings or a map[string]string. The basic idea is to provide a way to query the expected format and values for the command in question while trying to use Apply() on an already created Builder type.

So like Variables but returns a slice of the SignatureVar.name instead of the whole SignatureVar?

May include the prefix as well, because the string or slice of strings used to find the match might not contain the entire prefix. Nevertheless, if it is just SignateVar.Name we don’t convey the full meaning as these variables are not always required. Moreover, if the type happens to be CephChoices we must list the choices again. Looks like we need the entire SignatureElement 😉.

[phlogistonjohn]

I'm still a bit fuzzy on the request. I've attempted to add a convenient way to get an at-a-glance summary of a description by giving it a String method that produces a summary string containing the prefix and string representations of the variables. The SignatureVar type also gained a String method to help make this happen.
(I left it as separate commits for now to help things stand out)

I hope this is sufficient. As for API use I would generally expect the PrefixString/Prefix method and Variables methods to cover the remaining cases of having to walk over the contents of a command Description.

If you still think something is missing please share a (pseudocode) use case demonstrating what you think is missing becasue I'm struggling a bit with some of the prose comments.

[anoopcs9]

As discussed offline, we've decided to pursue the request later so that the core infrastructure can be merged first.

[anoopcs9]

lgtm.

[phlogistonjohn]

@ansiwen PTAL. If you can not approve by 04/13 my plan is to merge anyway but if changes are requested I'm happy to extend the preview period for this by an additional release. That's my plan since many of my prs tend to run long lately.

[phlogistonjohn]

@Mergifyio rebase

[mergify]

Deprecation notice: This pull request comes from a fork and was rebased using bot_account impersonation. This capability will be removed on July 1, 2026. After this date, the rebase action will no longer be able to rebase fork pull requests with this configuration. Please switch to the update action/command to ensure compatibility going forward.

[mergify]

rebase

✅ Branch has been successfully rebased