api: remaining bits for jsonstream, jsonmessage, progress cleanup #50575
Description
Description
Quick draft up of things still unclear in the "stream" cleanup, because my head is spinning with all the different types (and unclear which ones correspond with the actual API responses, because our swagger looks to be incomplete);
- api/pkg/streamformatter:
jsonMessage- non-exported type - api/pkg/progress:
Progressexported type - I THINK this is the actual type that goes over the wire (and should be inapi/types/?) - api/types/jsonstream:
Errorexported type - I THINK this is a type that goes over the wire (so should indeed be inapi/types/) - api/types/jsonstream:
Progressunclear; used by bothpkg/jsonmessage(client) andapi/types/streamformatter(only to read, or also to produce over the wire?) - ☝️ relation with
api/pkg/progress.Progress?
Also related;
- which parts of
api/pkg/streamformatterare used to produce and which to consume the streams? - the refactor introduces some "presentation" logic in
api/pkg/streamformatter(which would be "consume" by clients, and potentially "opinionated" on how to present) - ☝️ ideally we'd split the presentation part fo the
client/(as a "reference" implementation, but ideally; make it easy to provide your own), and only have core essentials for producing the streams (JSON) part of the API.
W.R.T. the various "Progress" types;
api/types/jsonstream.Progress:
// Progress describes a progress message in a JSON stream.
type Progress struct {
Current int64 `json:"current,omitempty"` // Current is the current status and value of the progress made towards Total.
Total int64 `json:"total,omitempty"` // Total is the end value describing when we made 100% progress for an operation.
Start int64 `json:"start,omitempty"` // Start is the initial value for the operation.
HideCounts bool `json:"hidecounts,omitempty"` // HideCounts. if true, hides the progress count indicator (xB/yB).
Units string `json:"units,omitempty"` // Units is the unit to print for progress. It defaults to "bytes" if empty.
}api/pkg/progress.Progress:
// Progress represents the progress of a transfer.
type Progress struct {
ID string
// Progress contains a Message or...
Message string
// ...progress of an action
Action string
Current int64
Total int64
// If true, don't show xB/yB
HideCounts bool
// If not empty, use units instead of bytes for counts
Units string
// Aux contains extra information not presented to the user, such as
// digests for push signing.
Aux interface{}
LastUpdate bool
}Then there's also api/types/events. (Type, Action are typed strings, Actor is a struct). It was referred to in on of the "stream" packages ("this <some stream type> is used for event streams), but maybe that was wrong.
// Message represents the information an event contains
type Message struct {
// Deprecated: use Action instead.
// Information from JSONMessage.
// With data only in container events.
Status string `json:"status,omitempty"`
// Deprecated: use Actor.ID instead.
ID string `json:"id,omitempty"`
// Deprecated: use Actor.Attributes["image"] instead.
From string `json:"from,omitempty"`
Type Type
Action Action
Actor Actor
// Engine events are local scope. Cluster events are swarm scope.
Scope string `json:"scope,omitempty"`
Time int64 `json:"time,omitempty"`
TimeNano int64 `json:"timeNano,omitempty"`
}Swagger
I think the api/types/progress.Progress struct is the API response type (also see #50565 (comment));
// Progress describes a progress message in a JSON stream.
type Progress struct {
Current int64 `json:"current,omitempty"` // Current is the current status and value of the progress made towards Total.
Total int64 `json:"total,omitempty"` // Total is the end value describing when we made 100% progress for an operation.
Start int64 `json:"start,omitempty"` // Start is the initial value for the operation.
HideCounts bool `json:"hidecounts,omitempty"` // HideCounts. if true, hides the progress count indicator (xB/yB).
Units string `json:"units,omitempty"` // Units is the unit to print for progress. It defaults to "bytes" if empty.
}If that's the case, our swagger definition doesn't match (is there another Go struct defined somewhere?);
Lines 2841 to 2847 in 2574c2b