Merge pull request #114 from alfrunes/file-transfer

ws/filetransfer: Update protocol schemas

ws/filetransfer/model.go

@@ -1,4 +1,4 @@
-// Copyright 2020 Northern.tech AS
+// Copyright 2021 Northern.tech AS
 //
 //    Licensed under the Apache License, Version 2.0 (the "License");
 //    you may not use this file except in compliance with the License.
@@ -14,64 +14,68 @@
 
 package filetransfer
 
+import "time"
+
 const (
-	MessageTypeGet          = "get_file"
-	MessageTypePut          = "put_file"
-	MessageTypeStat         = "file_info_req"
-	MessageTypeStatResponse = "file_info_res"
-	MessageTypeChunk        = "file_chunk"
-	MessageTypeError        = "error"
+	// MessageTypeGet requests a file from the device.
+	MessageTypeGet = "get_file"
+	// MessageTypePut requests a file upload to the device. The body MUST
+	// contain a FileInfo object.
+	MessageTypePut = "put_file"
+	// MessageTypeContinue is returned on upload requests when the client
+	// may start uploading file_chunks.
+	MessageTypeContinue = "put_file/continue"
+	// MessageTypeStat requests file information from the device. The body
+	// MUST contain a StatFile object.
+	MessageTypeStat = "stat"
+	// MessageTypeFileInfo is a response to a MessageTypeStat request.
+	// The body MUST contain a FileInfo object.
+	MessageTypeFileInfo = "file_info"
+	// MessageTypeChunk is the message type for streaming file chunks. The
+	// body contains a binary slice of the file, and optional "offset" property
+	// can be passed in the header.
+	MessageTypeChunk = "file_chunk"
+	// MessageTypeError is returned on internal or protocol errors. The
+	// body MUST contain an Error object.
+	MessageTypeError = "error"
 )
 
 // The Error struct is passed in the Body of MsgProto in case the message type is ErrorMessage
 type Error struct {
 	// The error description, as in "Permission denied while opening a file"
-	Error string `msgpack:"err" json:"error"`
+	Error *string `msgpack:"err" json:"error"`
 	// Type of message that raised the error
-	MessageType string `msgpack:"msgtype,omitempty" json:"message_type,omitempty"`
+	MessageType *string `msgpack:"msgtype,omitempty" json:"message_type,omitempty"`
 	// Message id is passed in the MsgProto Properties, and in case it is available and
 	// error occurs it is passed for reference in the Body of the error message
-	MessageID string `msgpack:"msgid,omitempty" json:"message_id,omitempty"`
+	MessageID *string `msgpack:"msgid,omitempty" json:"message_id,omitempty"`
 }
 
 // Get file requests the flow of MessageTypeFileChunk messages to be started from the remote end
 type GetFile struct {
 	// The file path to the file we are requesting
-	Path string `msgpack:"path,omitempty" json:"path,omitempty"`
-}
-
-// Put file marks the flow of MessageTypeFileChunk messages to be started to the remote end
-type PutFile struct {
-	// The file path to the file we are requesting
-	Path string `msgpack:"path,omitempty" json:"path,omitempty"`
+	Path *string `msgpack:"path,omitempty" json:"path,omitempty"`
 }
 
 // Stat file requests the file stat structure from the remote end
 type StatFile struct {
 	// The file path to the file we are requesting
-	Path string `msgpack:"path,omitempty" json:"path,omitempty"`
+	Path *string `msgpack:"path" json:"path,omitempty"`
 }
 
-// Stat file response is the reply to the StatFile from the remote end
-type StatFileResponse struct {
+// FileInfo is the object returned from a StatFile request and is also used
+// for "put_file" requests for specifying the target file.
+type FileInfo struct {
 	// The file path to the file we are sending status for
-	Path string `msgpack:"path,omitempty" json:"path,omitempty"`
+	Path *string `msgpack:"path" json:"path"`
 	// The file size
-	Size int64 `msgpack:"size,omitempty" json:"size,omitempty"`
-	// The file type
-	Type string `msgpack:"type,omitempty" json:"type,omitempty"`
+	Size *int64 `msgpack:"size,omitempty" json:"size,omitempty"`
 	// The file owner
-	Owner string `msgpack:"owner,omitempty" json:"owner,omitempty"`
+	UID *uint32 `msgpack:"uid,omitempty" json:"uid,omitempty"`
 	// The file group
-	Group string `msgpack:"group,omitempty" json:"group,omitempty"`
-}
-
-// File chunk carry the contents of the file
-type FileChunk struct {
-	// The current offset in the file
-	Offset string `msgpack:"offset,omitempty" json:"offset,omitempty"`
-	// The chunk size
-	Size string `msgpack:"chunksize,omitempty" json:"chunk_size,omitempty"`
-	// Array of bytes of file contents
-	Data []byte `msgpack:"data,omitempty" json:"data,omitempty"`
+	GID *uint32 `msgpack:"gid,omitempty" json:"gid,omitempty"`
+	// Mode contains the file mode and permission bits.
+	Mode *uint32 `msgpack:"mode,omitempty" json:"mode,omitempty"`
+	// ModTime is the last modification time for the file.
+	ModTime *time.Time `msgpack:"modtime,omitempty" json:"modification_time,omitempty"`
 }

ws/protomsg.go

@@ -30,6 +30,27 @@ const (
 	ProtoTypePortForward
 	// ProtoTypeMenderClient is used for communication with the Mender client.
 	ProtoTypeMenderClient
+
+	// ProtoTypeControl is a reserved proto type for session control messages.
+	ProtoTypeControl ProtoType = 0xFFFF
+)
+
+const (
+	// MessageTypes for session control messages (ProtoTypeControl),
+	// only the error message contains a body.
+
+	// MessageTypePing sends a ping. After receiving a ping, the receiver
+	// MUST respond with a pong message or the session will time out.
+	MessageTypePing = "ping"
+	// MessageTypePong is sent in response to a MessageTypePing.
+	MessageTypePong = "pong"
+	// MessageTypeClose is sent when the session MUST close. All
+	// communication on the session stop after receiving this message.
+	MessageTypeClose = "close"
+	// MessageTypeError is sent on a general protocol violation/error.
+	// An error message MUST contain an Error object. If the object's
+	// "close" field is set this message also closes the session.
+	MessageTypeError = "error"
 )
 
 // ProtoHdr provides the info about what the ProtoMsg contains and
@@ -67,3 +88,18 @@ func (m *ProtoMsg) Bind(b encoding.BinaryMarshaler) error {
 	m.Body = data
 	return err
 }
+
+// The Error struct is passed in the Body of MessageTypeError.
+type Error struct {
+	// The error description, as in "Permission denied while opening a file"
+	Error string `msgpack:"err" json:"error"`
+	// Close determines whether the session closed as a result of this error.
+	Close bool `msgpack:"close" json:"close"`
+	// MessageProto is the protocol of the message that caused the error.
+	MessageProto ProtoType `msgpack:"msgproto,omitempty" json:"message_protocol,omitempty"`
+	// Type of message that raised the error
+	MessageType string `msgpack:"msgtype,omitempty" json:"message_type,omitempty"`
+	// Message id is passed in the MsgProto Properties, and in case it is available and
+	// error occurs it is passed for reference in the Body of the error message
+	MessageID string `msgpack:"msgid,omitempty" json:"message_id,omitempty"`
+}