add comments for data structure and API functions (70573854) · Commits · kinetic-archive / kinetic-go

blockconnection.go

+7 −3

Original line number	Diff line number	Diff line
		@@ -170,7 +170,7 @@ func (conn BlockConnection) Put(entry Record) (Status, error) {
		return callback.Status(), err
		}

		// P2Push
		// P2PPush performs peer to peer push operation
		func (conn BlockConnection) P2PPush(request P2PPushRequest) (*P2PPushStatus, Status, error) {
		callback := &P2PPushCallback{}
		h := NewResponseHandler(callback)
		@@ -391,7 +391,9 @@ func (conn *BlockConnection) SetACL(acls []ACL) (Status, error) {
		return callback.Status(), err
		}

		// MediaScan
		// MediaScan is to check that the user data is readable, and
		// if the end to end integrity is known to the device, if the
		// end to end integrity field is correct.
		func (conn BlockConnection) MediaScan(op MediaOperation, pri Priority) (Status, error) {
		callback := &GenericCallback{}
		h := NewResponseHandler(callback)
		@@ -405,7 +407,9 @@ func (conn BlockConnection) MediaScan(op MediaOperation, pri Priority) (Status
		return callback.Status(), err
		}

		// MediaOptimize
		// MediaOptimize performs optimizations of the media. Things like
		// defragmentation, compaction, garbage collection, compression
		// could be things accomplished using the media optimize command.
		func (conn BlockConnection) MediaOptimize(op MediaOperation, pri Priority) (Status, error) {
		callback := &GenericCallback{}
		h := NewResponseHandler(callback)

getlog.go

+12 −0

Original line number	Diff line number	Diff line
		@@ -24,6 +24,7 @@ import (
		// LogType defines what type of information to retrieve by GetLog.
		type LogType int32

		// LogType values
		const (
		_ LogType = iota
		LogTypeUtilizations LogType = iota
		@@ -177,6 +178,17 @@ type LimitsLog struct {
		MaxBatchCountPerDevice uint32 //
		}

		// DeviceLog is to ask the device to send back the
		// log of a certain name in the value field. The limit of each
		// log is 1m byte.
		//
		// Proprietary names should be prefaced by the vendor name so that name
		// collisions do not happen in the future. An example could be names that
		// start with “com.WD” would be for Western Digital devices.
		//
		// If the name is not found, the get log returns NOT_FOUND.
		//
		// There can be only one Device in the list of logs that can be retrieved.!
		type DeviceLog struct {
		Name []byte
		}

kinetic.go

+28 −10

Original line number	Diff line number	Diff line
		@@ -42,6 +42,7 @@ func init() {
		type LogLevel logrus.Level

		const (
		// LogLevelPanic level. Panic.
		LogLevelPanic LogLevel = LogLevel(logrus.PanicLevel)
		// LogLevelFatal level. Logs and then calls `os.Exit(1)`. It will exit even if the
		// logging level is set to Panic.
		@@ -80,6 +81,7 @@ type ClientOptions struct {
		// MessageType defines the top level kinetic command message type.
		type MessageType int32

		// MessageType for each message exchanged between kinetic device and client
		const (
		_ MessageType = iota
		MessageGet MessageType = iota
		@@ -349,9 +351,10 @@ func convertMessageTypeFromProto(m kproto.Command_MessageType) MessageType {
		return ret
		}

		// Algorithm
		// Algorithm defines the which algorithm used to protect data.
		type Algorithm int32

		// Algorithm to protect data
		const (
		_ Algorithm = iota
		AlgorithmSHA1 Algorithm = iota
		@@ -417,14 +420,15 @@ func convertAlgoFromProto(a kproto.Command_Algorithm) Algorithm {
		return ret
		}

		// Synchronization allows the puts and deletes to determine if they are to be
		// SYNC_WRITETHROUGH: This request is made persistent before returning. This does not effect any other pending operations.
		// SYNC_WRITEBACK: They can be made persistent when the device chooses, or when a subsequent FLUSH is give to the device.
		// SYNC_FLUSH: All pending information that has not been written is pushed to the disk and the command that specifies
		// FLUSH is written last and then returned. All WRITEBACK writes that have received ending status will be guaranteed
		// to be written before the FLUSH operation is returned completed.
		// Synchronization allows the puts and deletes to determine how to make data persistent.
		type Synchronization int32

		// Syncchronization types
		// SyncWriteThrough: This request is made persistent before returning. This does not effect any other pending operations.
		// SyncWriteBack: They can be made persistent when the device chooses, or when a subsequent FLUSH is give to the device.
		// SyncFlush: All pending information that has not been written is pushed to the disk and the command that specifies
		// FLUSH is written last and then returned. All WRITEBACK writes that have received ending status will be guaranteed
		// to be written before the FLUSH operation is returned completed.
		const (
		_ Synchronization = iota
		SyncWriteThrough Synchronization = iota
		@@ -472,8 +476,12 @@ func convertSyncFromProto(sync kproto.Command_Synchronization) Synchronization {
		return ret
		}

		// Priority is a simple integer that determines the priority of this
		// request. All activity at a higher priority will execute before that
		// of lower priority traffic. A higher number is higher priority.
		type Priority int32

		// Priority level from lowest to highest.
		const (
		_ Priority = iota
		PriorityLowest Priority = iota
		@@ -533,6 +541,7 @@ func convertPriorityFromProto(p kproto.Command_Priority) Priority {
		return ret
		}

		// Record structure defines information for an object stored on kinetic device.
		type Record struct {
		Key []byte
		Value []byte
		@@ -544,6 +553,7 @@ type Record struct {
		MetaOnly bool
		}

		// KeyRange structure defines the range for GetRange operation.
		type KeyRange struct {
		StartKey []byte
		EndKey []byte
		@@ -553,6 +563,7 @@ type KeyRange struct {
		Max int32
		}

		// MediaOperation structure defines media operation information for MediaScan and MediaOptimize.
		type MediaOperation struct {
		StartKey []byte
		EndKey []byte
		@@ -560,8 +571,10 @@ type MediaOperation struct {
		EndKeyInclusive bool
		}

		// ACLPermission defines what operations a user identity can perform.
		type ACLPermission int32

		// ACLPermission for various type of operation.
		const (
		_ ACLPermission = iota
		ACLPermissionRead ACLPermission = iota // Can read key/values
		@@ -645,8 +658,10 @@ func convertACLPermissionFromProto(perm kproto.Command_Security_ACL_Permission)
		return ret
		}

		// ACLAlgorithm defines the HMAC algorithm.
		type ACLAlgorithm int32

		// ACLAlgorithm values.
		const (
		_ ACLAlgorithm = iota
		ACLAlgorithmHMACSHA1 ACLAlgorithm = iota
		@@ -673,6 +688,7 @@ func convertACLAlgorithmToProto(algo ACLAlgorithm) kproto.Command_Security_ACL_H
		return ret
		}

		// ACLScope defines scope of ACL.
		type ACLScope struct {
		Offset int64
		Value []byte
		@@ -680,6 +696,7 @@ type ACLScope struct {
		TLSRequired bool
		}

		// ACL structure for SetACL call. Defines permission for identity.
		type ACL struct {
		Identify int64
		Key []byte
		@@ -688,7 +705,7 @@ type ACL struct {
		MaxPriority Priority
		}

		// P2PPushOperation
		// P2PPushOperation structure for P2PPush operation.
		type P2PPushOperation struct {
		Key []byte // Key for the object to push to peer kinetic device
		Version []byte
		@@ -697,7 +714,7 @@ type P2PPushOperation struct {
		Request *P2PPushRequest // Chain P2PPushRequest, which will perform on peer kinetic device
		}

		// P2PPushRequest
		// P2PPushRequest structure for P2PPush operation
		type P2PPushRequest struct {
		HostName string // Peer kinetic device IP / hostname
		Port int32 // Peer kinetic drvice port
		@@ -720,9 +737,10 @@ type BatchStatus struct {
		FailedSequence int64 // Non 0 value means the first failed operation sequence in the batch, 0 means no failure
		}

		// PowerLevel
		// PowerLevel defines the power level of kinetic device.
		type PowerLevel int32

		// PowerLevel values.
		const (
		_ PowerLevel = iota
		PowerLevelOperational PowerLevel = iota

nonblockconnection.go

+9 −2

Original line number	Diff line number	Diff line
		@@ -33,7 +33,7 @@ type NonBlockConnection struct {
		batchMu sync.Mutex
		}

		// Helper function to establish non-block connection to device.
		// NewNonBlockConnection is helper function to establish non-block connection to device.
		func NewNonBlockConnection(op ClientOptions) (*NonBlockConnection, error) {
		if op.Hmac == nil {
		klog.Panic("HMAC is required for ClientOptions")
		@@ -212,7 +212,7 @@ func (conn NonBlockConnection) buildP2PMessage(request P2PPushRequest) *kproto
		return p2pop
		}

		// P2Push
		// P2PPush performs peer to peer push operation
		func (conn NonBlockConnection) P2PPush(request P2PPushRequest, h *ResponseHandler) error {
		msg := newMessage(kproto.Message_HMACAUTH)
		cmd := newCommand(kproto.Command_PEER2PEERPUSH)
		@@ -450,6 +450,9 @@ func (conn NonBlockConnection) SetACL(acls []ACL, h ResponseHandler) error {
		return conn.service.submit(msg, cmd, nil, h)
		}

		// MediaScan is to check that the user data is readable, and
		// if the end to end integrity is known to the device, if the
		// end to end integrity field is correct.
		func (conn NonBlockConnection) MediaScan(op MediaOperation, pri Priority, h *ResponseHandler) error {
		msg := newMessage(kproto.Message_HMACAUTH)

		@@ -470,6 +473,9 @@ func (conn NonBlockConnection) MediaScan(op MediaOperation, pri Priority, h *R
		return conn.service.submit(msg, cmd, nil, h)
		}

		// MediaOptimize performs optimizations of the media. Things like
		// defragmentation, compaction, garbage collection, compression
		// could be things accomplished using the media optimize command.
		func (conn NonBlockConnection) MediaOptimize(op MediaOperation, pri Priority, h *ResponseHandler) error {
		msg := newMessage(kproto.Message_HMACAUTH)

		@@ -490,6 +496,7 @@ func (conn NonBlockConnection) MediaOptimize(op MediaOperation, pri Priority,
		return conn.service.submit(msg, cmd, nil, h)
		}

		// SetPowerLevel sets device power level
		func (conn NonBlockConnection) SetPowerLevel(p PowerLevel, h ResponseHandler) error {
		msg := newMessage(kproto.Message_HMACAUTH)

status.go

+1 −0

Original line number	Diff line number	Diff line
		@@ -27,6 +27,7 @@ import (
		// Including status code get from device, or client internal error code.
		type StatusCode int32

		// StatusCode code value
		const (
		RemoteNotAttempted StatusCode = iota
		OK StatusCode = iota