refactor: extract inspect rendering logic to be display handlers #1150

JeyJeyGao · 2025-01-16T09:21:40Z

Depends on spec change: #1156

Refactor:

Extract output formatting logic from the inspect command layer to an isolated display handler layer for processing rendering.
Add json and tree inspect handlers.

Fix:

For tree output, make the key names with multiple words separated by space characters rather than capitalizing the words, which is defined in the inspect command spec.
For json output, default to rendering time in RFC3339 with nanoseconds (Notation expiry, signing time and certificate expiry are accurate to 1 second. Timestamp RFC 3161 can have fraction-of-second time value).

E2E Test:

inspect signature with timestamp, signature expiry and user metadata (text, json)
inspect signatures with invalid timestamp (test, json)
inspect with -o shorthand.

Resolves part of #1151

Signed-off-by: Junjie Gao <[email protected]>

codecov · 2025-01-16T09:24:14Z

Codecov Report

Attention: Patch coverage is 88.69863% with 33 lines in your changes missing coverage. Please review.

Project coverage is 74.71%. Comparing base (2920cae) to head (da16190).
Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...notation/internal/display/metadata/tree/inspect.go	87.12%	9 Missing and 4 partials ⚠️
...notation/internal/display/metadata/json/inspect.go	89.32%	8 Missing and 3 partials ⚠️
...md/notation/internal/display/metadata/tree/tree.go	40.00%	4 Missing and 2 partials ⚠️
cmd/notation/inspect.go	85.71%	0 Missing and 2 partials ⚠️
internal/envelope/envelope.go	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1150      +/-   ##
==========================================
+ Coverage   73.30%   74.71%   +1.41%     
==========================================
  Files          53       59       +6     
  Lines        3240     3338      +98     
==========================================
+ Hits         2375     2494     +119     
+ Misses        671      651      -20     
+ Partials      194      193       -1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Signed-off-by: Junjie Gao <[email protected]>

cmd/notation/internal/output/print.go

cmd/notation/inspect.go

cmd/notation/internal/display/metadata/interface.go

cmd/notation/internal/display/metadata/model/signature.go

Signed-off-by: Junjie Gao <[email protected]>

cmd/notation/internal/option/format.go

shizhMSFT · 2025-01-20T10:24:54Z

cmd/notation/internal/option/common.go

+// Common option struct.
+type Common struct {
+	Printer *output.Printer
+}


Will you refactor --debug in later PRs?

Yes, it is part of this issue #1151

shizhMSFT · 2025-01-20T10:26:17Z

cmd/notation/inspect.go

+			if err := opts.Format.Parse(cmd); err != nil {
+				return err
+			}
+			if err := opts.Common.Parse(cmd); err != nil {
+				return err
+			}


You may want https://github.com/oras-project/oras/blob/main/cmd/oras/internal/option/parser.go

Yes, I noticed that, but I chose to include it in future PRs. It is part of this issue: #1151

cmd/notation/internal/display/metadata/interface.go

cmd/notation/internal/display/metadata/tree/inspect.go

Signed-off-by: Junjie Gao <[email protected]>

cmd/notation/inspect.go

Signed-off-by: Junjie Gao <[email protected]>

cmd/notation/internal/output/print.go

cmd/notation/internal/display/metadata/json/inspect.go

cmd/notation/internal/option/format.go

cmd/notation/internal/output/json.go

Two-Hearts · 2025-01-21T09:02:35Z

internal/envelope/envelope.go

@@ -61,21 +61,21 @@ func ValidatePayloadContentType(payload *signature.Payload) error {

 // DescriptorFromPayload parses a signature payload and returns the descriptor
 // that was signed. Note: the descriptor was signed but may not be trusted
-func DescriptorFromSignaturePayload(payload *signature.Payload) (*ocispec.Descriptor, error) {
+func DescriptorFromSignaturePayload(payload *signature.Payload) (ocispec.Descriptor, error) {


Any reason to make this change? It seems not related to this PR though.

It was suggested here: #1150 (comment). I think this is a convention of ORAS.

~~OK, I removed the update to envelope.go as it is not closely related to this refactor work.~~

@Two-Hearts ocispec.Descriptor should be used as a structure is a convention start from image-spec. We should follow the same patten: https://pkg.go.dev/github.com/opencontainers/[email protected]/specs-go/v1#Manifest

cmd/notation/internal/display/metadata/interface.go

Signed-off-by: Junjie Gao <[email protected]>

shizhMSFT

LGTM

Signed-off-by: Junjie Gao <[email protected]>

Two-Hearts · 2025-01-23T02:32:37Z

cmd/notation/internal/output/print.go

+limitations under the License.
+*/
+
+package output


Now we have a folder called display, then another folder called output.
I have a feeling that we are making the code structure more and more complicated. And this may bring in difficulty for other developers to read through and understand such complicity in the future.

Refactored and moved output to display/output

Two-Hearts · 2025-01-23T02:33:54Z

internal/tree/tree.go

Same here. We have a folder called tree, then another folder with the same name under cmd/notation/internal/display/metadata. Can we try to reduce such complicity during the design phase?

Refactored.

Signed-off-by: Junjie Gao <[email protected]>

shizhMSFT

I noticed that handlers are grouped by command names instead of format types. Although both are acceptable, grouping by format types can have more benefits in the long run, especially we have growing commands but fixed set of format types.

One important point is that grouping by format types make developers easier to have consistent output for a certain format type across all commands.

Also, it is easier to have common utility functions without creating a utility package, which is discouraged.

Signed-off-by: Junjie Gao <[email protected]>

JeyJeyGao · 2025-01-23T08:26:20Z

I noticed that handlers are grouped by command names instead of format types. Although both are acceptable, grouping by format types can have more benefits in the long run, especially we have growing commands but fixed set of format types.

One important point is that grouping by format types make developers easier to have consistent output for a certain format type across all commands.

Also, it is easier to have common utility functions without creating a utility package, which is discouraged.

Updated to group the handlers by format types.

shizhMSFT · 2025-01-23T08:25:28Z

cmd/notation/internal/display/handler.go

-func NewInpsectHandler(printer *output.Printer, format option.Format) (metadata.InspectHandler, error) {
+// NewMetadataInpsectHandler creates a new InspectHandler based on the output
+// format.
+func NewMetadataInpsectHandler(printer *output.Printer, format option.Format) (metadata.InspectHandler, error) {


Let's call it NewInpsectHandler.

In the package display, the function name is intended to be

func New{{.CommandName}}Handler({{.parameters}}) (status.{{.CommandName}}Handler, metadata.{{.CommandName}}Handler, error)

although we dont have status support yet.

Updated to NewInpsectHandler

Signed-off-by: Junjie Gao <[email protected]>

shizhMSFT

LGTM

Signed-off-by: Junjie Gao <[email protected]>

shizhMSFT

LGTM

refactor: add inpect display handler

89adf15

Signed-off-by: Junjie Gao <[email protected]>

JeyJeyGao added 3 commits January 16, 2025 10:21

fix: update code

f0756a8

Signed-off-by: Junjie Gao <[email protected]>

test: add unit test

578dea2

Signed-off-by: Junjie Gao <[email protected]>

test: add e2e test for tree and json

24dea8b

Signed-off-by: Junjie Gao <[email protected]>

shizhMSFT reviewed Jan 17, 2025

View reviewed changes

JeyJeyGao added 8 commits January 17, 2025 09:08

refactor code

4031faf

Signed-off-by: Junjie Gao <[email protected]>

fix: update E2E

37b967a

Signed-off-by: Junjie Gao <[email protected]>

fix: resolve comments

c2697db

Signed-off-by: Junjie Gao <[email protected]>

fix: update license header

edbfbad

Signed-off-by: Junjie Gao <[email protected]>

fix: update test

eb078e3

Signed-off-by: Junjie Gao <[email protected]>

test: add unit test

4d3aedd

Signed-off-by: Junjie Gao <[email protected]>

test: add unit test for inspect

8fdc989

Signed-off-by: Junjie Gao <[email protected]>

test: update test

0640165

Signed-off-by: Junjie Gao <[email protected]>

JeyJeyGao marked this pull request as ready for review January 20, 2025 08:39

JeyJeyGao requested review from gokarnm, NiazFK, priteshbandi, rgnote, toddysm, Two-Hearts, vaninrao10 and yizha1 as code owners January 20, 2025 08:39

JeyJeyGao changed the title ~~refactor: add inspect display handler~~ refactor: extract inspect rendering logic to be display handlers Jan 20, 2025

shizhMSFT requested changes Jan 20, 2025

View reviewed changes

JeyJeyGao added 2 commits January 21, 2025 01:44

fix: resolve comemnts

a1e411f

Signed-off-by: Junjie Gao <[email protected]>

fix: test

84a1991

Signed-off-by: Junjie Gao <[email protected]>

JeyJeyGao requested a review from shizhMSFT January 21, 2025 01:54

fix: remove envelope media type

8083c25

Signed-off-by: Junjie Gao <[email protected]>

Two-Hearts mentioned this pull request Jan 21, 2025

docs: fix inspect command spec #1156

Merged

Two-Hearts reviewed Jan 21, 2025

View reviewed changes

cmd/notation/inspect.go Show resolved Hide resolved

JeyJeyGao marked this pull request as draft January 21, 2025 03:35

JeyJeyGao added 2 commits January 21, 2025 06:23

fix: e2e test

5dd55ca

Signed-off-by: Junjie Gao <[email protected]>

fix: e2e test

25bc6a0

Signed-off-by: Junjie Gao <[email protected]>

JeyJeyGao marked this pull request as ready for review January 21, 2025 06:38

JeyJeyGao added 2 commits January 21, 2025 07:13

fix: update json output format

fd74cf7

Signed-off-by: Junjie Gao <[email protected]>

fix: update e2e

f1c2966

Signed-off-by: Junjie Gao <[email protected]>

JeyJeyGao requested a review from Two-Hearts January 21, 2025 07:42

JeyJeyGao added 3 commits January 21, 2025 08:25

fix: add content type in json output

89b310f

Signed-off-by: Junjie Gao <[email protected]>

test: add e2e test for invalid timestamp signature

58603ce

Signed-off-by: Junjie Gao <[email protected]>

fix: update e2e test

b3a97e5

Signed-off-by: Junjie Gao <[email protected]>

Two-Hearts reviewed Jan 21, 2025

View reviewed changes

JeyJeyGao added 2 commits January 21, 2025 09:31

fix: unit test

b108fcd

Signed-off-by: Junjie Gao <[email protected]>

fix: resolve comments

721518a

Signed-off-by: Junjie Gao <[email protected]>

shizhMSFT previously approved these changes Jan 22, 2025

View reviewed changes

fix: resolve comments

0997875

Signed-off-by: Junjie Gao <[email protected]>

JeyJeyGao dismissed shizhMSFT’s stale review via 0997875 January 23, 2025 02:33

Two-Hearts reviewed Jan 23, 2025

View reviewed changes

JeyJeyGao added 2 commits January 23, 2025 05:16

refactor: display package structure

aef5735

Signed-off-by: Junjie Gao <[email protected]>

fix: update to use *ocispec.Descriptor

5b28eda

Signed-off-by: Junjie Gao <[email protected]>

shizhMSFT reviewed Jan 23, 2025

View reviewed changes

fix: restore package structure

8f5d88f

Signed-off-by: Junjie Gao <[email protected]>

shizhMSFT reviewed Jan 23, 2025

View reviewed changes

fix: restore "NewInpsectHandler" function name

1adc392

Signed-off-by: Junjie Gao <[email protected]>

shizhMSFT previously approved these changes Jan 23, 2025

View reviewed changes

fix: move internal/tree to tree handlers package

da16190

Signed-off-by: Junjie Gao <[email protected]>

JeyJeyGao dismissed shizhMSFT’s stale review via da16190 January 23, 2025 08:41

shizhMSFT approved these changes Jan 23, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: extract inspect rendering logic to be display handlers #1150

refactor: extract inspect rendering logic to be display handlers #1150

JeyJeyGao commented Jan 16, 2025 •

edited

Loading

codecov bot commented Jan 16, 2025 •

edited

Loading

shizhMSFT Jan 20, 2025

JeyJeyGao Jan 21, 2025

shizhMSFT Jan 20, 2025

JeyJeyGao Jan 21, 2025

Two-Hearts Jan 21, 2025

JeyJeyGao Jan 22, 2025

JeyJeyGao Jan 23, 2025 •

edited

Loading

JeyJeyGao Jan 23, 2025

shizhMSFT left a comment

Two-Hearts Jan 23, 2025

JeyJeyGao Jan 23, 2025

Two-Hearts Jan 23, 2025

JeyJeyGao Jan 23, 2025

shizhMSFT left a comment

JeyJeyGao commented Jan 23, 2025

shizhMSFT Jan 23, 2025

JeyJeyGao Jan 23, 2025

shizhMSFT left a comment

shizhMSFT left a comment

refactor: extract inspect rendering logic to be display handlers #1150

Are you sure you want to change the base?

refactor: extract inspect rendering logic to be display handlers #1150

Conversation

JeyJeyGao commented Jan 16, 2025 • edited Loading

codecov bot commented Jan 16, 2025 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JeyJeyGao Jan 23, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shizhMSFT left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shizhMSFT left a comment

Choose a reason for hiding this comment

JeyJeyGao commented Jan 23, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shizhMSFT left a comment

Choose a reason for hiding this comment

shizhMSFT left a comment

Choose a reason for hiding this comment

JeyJeyGao commented Jan 16, 2025 •

edited

Loading

codecov bot commented Jan 16, 2025 •

edited

Loading

JeyJeyGao Jan 23, 2025 •

edited

Loading