Let's refactor the nerdctl CLI package

[Zheaoli]

Update in 2022-12-26

After some discussion on this issue, most of the nerdctl maintainers reach the same point.

We need to refactor the command flagging process. After the refactor process, all logic in cmd package should only validate cobra flags and construct the CommandOption.

Refactor Check List:

• Create a file in pkg/api/types/${cmd}_types.go, and define the CommandOption for this command
• Create some file in pkg/cmd/${cmd}, and move the command entry point in real into this package
• [ ] Create new docs in docs/reference/api/${cmd}_types.md, and describe the field in CommandOption

I will create single issue for each subcommand

• Refactor the apparmor command flagging process Refactor the apparmor flagging process #1774
• Refactor the build command flagging process #1689
• Refactor the commit command flagging process #1690
• Refactor the compose command flagging process #1691
• Refactor the compose build command flagging process #1692
• Refactor the compose config command flagging process #1693
• Refactor the compose create command flagging process #1694
• Refactor the compose down command flagging process #1695
• Refactor the compose exec command flagging process #1696
• Refactor the compose images command flagging process #1697
• Refactor the compose kill command flagging process #1698
• Refactor the compose log command flagging process #1699
• Refactor the compose pause command flagging process #1700
• Refactor the compose port command flagging process #1701
• Refactor the compose ps command flagging process #1702
• Refactor the compose pull command flagging process #1703
• Refactor the compose push command flagging process #1704
• Refactor the compose rm command flagging process #1705
• Refactor the compose run command flagging process #1706
• Refactor the compose start command flagging process #1707
• Refactor the compose stop command flagging process #1708
• Refactor the compose top command flagging process #1709
• Refactor the compose up command flagging process #1711
• Refactor the compose version command flagging process #1710
• Refactor the container command flagging process #1712
• Refactor the container inspect command flagging process #1713
• Refactor the container prune command flagging process #1714
• Refactor the cp command flagging process #1716
• Refactor the exec command flagging process #1715
• Refactor the history command flagging process #1717
• Refactor the image command flagging process #1718
• Refactor the image convert command flagging process #1719
• Refactor the image encrypt command flagging process #1720
• Refactor the image decrypt command flagging process #1721
• Refactor the image inspect command flagging process #1722
• Refactor the image prune command flagging process #1723
• Refactor the images command flagging process #1724
• Refactor the info command flagging process #1725
• Refactor the inspect command flagging process #1726
• Refactor the ipfs command flagging process #1727
• Refactor the ipfs registry command flagging process #1728
• Refactor the kill command flagging process #1729
• Refactor the load command flagging process #1730
• Refactor the login command flagging process #1731
• Refactor the logout command flagging process #1732
• Refactor the logs command flagging process #1734
• Refactor the namepace command flagging process #1733
• Refactor the namespace create command flagging process #1735
• Refactor the namespace rm command flagging process #1736
• Refactor the namespace update command flagging process #1737
• Refactor the network command flagging process #1738
• Refactor the network create command flagging process #1739
• Refactor the network inspect command flagging process #1740
• Refactor the network ls command flagging process #1741
• Refactor the network prune command flagging process #1742
• Refactor the network rm command flagging process #1743
• Refactor the pause command flagging process #1744
• Refactor the port command flagging process #1745
• Refactor the ps command flagging process #1746
• Refactor the pull command flagging process #1747
• Refactor the push command flagging process #1748
• Refactor the rename command flagging process #1749
• Refactor the restart command flagging process #1750
• Refactor the rm command flagging process #1751
• Refactor the rmi command flagging process #1752
• Refactor the run command flagging process #1753
• Refactor the save command flagging process #1754
• Refactor the stats command flagging process #1755
• Refactor the start command flagging process #1756
• Refactor the stop command flagging process #1757
• Refactor the system command flagging process #1758
• Refactor the unpause command flagging process #1759
• Refactor the update command flagging process #1760
• Refactor the version command flagging process #1761
• Refactor the volume command flagging process #1762
• Refactor the volume create command flagging process #1763
• Refactor the volume inspect command flagging process #1764
• Refactor the volume ls command flagging process #1765
• Refactor the volume prune command flagging process #1766
• Refactor the volume rm command flagging process #1767
• Refactor the volume wait command flagging process #1768

What is the problem you're trying to solve

OK, I'm back!

For now, the cmd package has a lot of go files mixed. It takes a lot of work to keep maintainer to maintain this project.

And in the community, people may need to add some features of their own, like #1631, so it's time to refactor the command package!

Describe the solution you'd like

I have made a previous PR, #1639; it's a nasty case for the community.

We may need to make some changes to make this issue happen.

I want to split this issue into three stages.

First: we need to decompose the flagging process in the command entry point

For now, we mix the flagging register and flagging process, like https://github.com/containerd/nerdctl/blob/main/cmd/nerdctl/exec.go#L53-L62

It means we can not split the common logic unrelated to cobra.Command, and care about the flag value from the current cmd package.

We can take a look at some projects in the community alike https://github.com/prometheus/prometheus/blob/main/cmd/prometheus/main.go#L127-L159 and
https://github.com/containers/podman/blob/main/cmd/podman/containers/attach.go#L45-L54, we will find out that we may collect the flag value into a centralize struct, so we do not need care about the cobra.Command in the entry point in real.

Second: split the common function into another package

For now, the cmd package maybe can be grouped into three types.

1. helper function, like https://github.com/containerd/nerdctl/blob/main/cmd/nerdctl/client.go
2. shellCompletion , like https://github.com/containerd/nerdctl/blob/main/cmd/nerdctl/client.go
3. the logic function, mixed with the flag process logic, like https://github.com/containerd/nerdctl/blob/main/cmd/nerdctl/apparmor_ls_linux.go#L56

In this stage, we need to do three things.

1. make the helper function out of the cmd package
2. make the shellCompletion together
3. after stage1, we can split the logic function into the pkg/ (for now, we don't need care about the cobra action in the logic function now!)

Third: restructed the cmd package by the subcommand

And now, we can restruct the cmd package by subcommand. The code in the cmd package has already been cleaned and will focus on the logic to process the flag. So the restruct process will be easy.

And the final problem in this stage the integration test would be a problem. For most circumstances, the integration test may be written with the command. But here's some in issue in go test, the go test command will run the test in different directory parallel, so there would be some potential conflict in this circumstance. I would prefer to make all the integration tests into a single directory together.

Additional context

No response

[AkihiroSuda]

Before working on this we have to revisit whether we really need to split the pkgs, and what are potential drawbacks.

I would prefer to make all the integration tests into a single directory together.

I'd expect the subcommand.go and the subcommand_test.go to be placed in the same directory, otherwise contributors can't find where to add tests.

[Zheaoli]

Before working on this we have to revisit whether we really need to split the pkgs, and what are potential drawbacks

Totally agree, but I think the stage1(refactoring the flag is needed whether we need to split it or not)

I'd expect the subcommand.go and the subcommand_test.go to be placed in the same directory, otherwise contributors can't find where to add tests.

I'm not sure if there is any way to run the go test in a non-parallel way. There will be some conflict in here, for example, we split the compose and the container * in different sub-command packages. The tests which open the same 80 local port will be run at the same time, so one of the tests will be failed because of the port conflict

[djdongjin]

I think maybe we can first focus more on the 1st step, which itself will significantly simplify our codebase by drawing a clear separation between flag/cobra processing and core logic processing.

Then we can have better sense on how to proceed to next steps (move logic functions to approriate packages) because they will be more modularized and not depends on flags/cobra.

1. I agree each command should have a CommandOption struct, regardless small or large. We should put them in a separate pkg (e.g., api/types.go, or pkg/api/types.go).
2. Then cmd/command.go should only validate cobra flags and construct the CommandOption, then pass it to pkg/command.go (or at least to a separate process func that accept CommandOption).

Most nerdctl compose related commands follows this pattern, and I found it's more clear and easy to find where the real logic is.

Although even doing 1st step might also involve moving some helper functions, probably that shouldn't be the main focus during this stage.

[Zheaoli]

• I agree each command should have a CommandOption struct, regardless small or large. We should put them in a separate pkg (e.g., api/types.go, or pkg/api/types.go).
• Then cmd/command.go should only validate cobra flags and construct the CommandOption, then pass it to pkg/command.go (or at least to a separate process func that accept CommandOption).

Totally agree, maybe we can refactor this subcommand by subcommand cc @AkihiroSuda @fahedouch

If we reach a consensus, I will split step1 into multi-subtask(most of the subtasks would be great good-first-issue(lol

[fahedouch]

Welcome back @Zheaoli 👋,

I agree each command should have a CommandOption struct, regardless small or large. We should put them in a separate pkg (e.g., api/types.go, or pkg/api/types.go).

I like the idea of having pkg/apis/ that contains the API resource definitions. We can split api files based on corresponding feature type:

• pkg/apis/run_types.go
• pkg/apis/container_management_types.go
• pkg/apis/image_management_types.go
• pkg/apis/compose_types.go
• pkg/apis/stats_types.go
• etc..

So contributors edit the *_types.go files to implement their API definitions. ( I was inspired by kubebuilder Project Creation and Structure ).

Then cmd/command.go should only validate cobra flags and construct the CommandOption, then pass it to pkg/command.go (or at least to a separate process func that accept CommandOption).

agreed, this will improve code readability.

---

refactor this subcommand by subcommand

I think before thinking about refactoring subcommand(s) , we need to ask :

• do we really have to split subcommands by subcommand ?

As the subcommands themselves aren't really designed to be imported from other projects. Every function related to subcommands and need to be imported should be under pkg/...
Then there might be no good reason to split cmd/nerdctl ?

---

Now regarding *_test.go. I found more practical to have subcommand.go and the subcommand_test.go to be placed in the same directory. Otherwise, it will be very time consuming.

[Zheaoli]

Welcome back @Zheaoli wave,

Thanks(lol

I like the idea of having pkg/apis/ that contains the API resource definitions. We can split api files based on corresponding feature type:

• pkg/apis/run_types.go
• pkg/apis/container_management_types.go
• pkg/apis/image_management_types.go
• pkg/apis/compose_types.go
• pkg/apis/stats_types.go
• etc..

So contributors edit the *_types.go files to implement their API definitions. ( I was inspired by kubebuilder Project Creation and Structure ).

Then cmd/command.go should only validate cobra flags and construct the CommandOption, then pass it to pkg/command.go (or at least to a separate process func that accept CommandOption).

agreed, this will improve code readability.

It seems we have reached the same point. we need to refactor the codebase to split the CommandOptiton and the flagging process"! We can discuss this later after we finish the flagging refactor step. In my thought, if we can make the Then cmd/command.go should only validate cobra flags and construct the CommandOption, we may don't need to split the cmd package

[Zheaoli]

What are other people's thoughts? @containerd/nerdctl-reviewers @containerd/nerdctl-committers

[AkihiroSuda]

Then cmd/command.go should only validate cobra flags and construct the CommandOption, we may don't need to split the cmd package

SGTM

[yuchanns]

Somewhat confused about a bunch of closed issues presented in your description. If you're going to add a number of good first issues, I would like to suggest that you leave only tasks here and ppl can open issues by themselves. As for tracking, it's enough for others simply make references to the issue.