Haptic Frames

HapticFrame:
1b - Header | 2b - Frame Length | Nb - Data

Header: 1 byte identifying the application message (frame type).
Length: Total size of the frame, including the Header and Length fields.
Data:   Payload, up to 1018 bytes. Preferred encoding: Protobuf.

const (
	headerLength  = 3
	maxDataLength = 1021 // the whole frame, not just the payload
)

var (
	ErrUnexpectedFrameType = errors.New("unexpected frame type")
	ErrUnknownFrameType    = errors.New("unknown frame type")
	ErrStreamIsNil         = errors.New("stream is nil")
)

// ErrInvalidLength is a function, not a sentinel — it carries the offending length.
func ErrInvalidLength(length int) error {
	return fmt.Errorf("invalid frame length %d", length)
}

// readN reads until n bytes are fetched.
// Some implementations may not return all bytes at once.
func readN(s io.Reader, n int) ([]byte, int, error) {
	k := 0
	buf := make([]byte, n)

	for k < n {
		kk, err := s.Read(buf[k:])
		if err != nil {
			return nil, k, err
		}

		k += kk
	}

	return buf, k, nil
}

type HapticFrame struct {
	Type       entities.FrameType
	Data       []byte
	dataLength uint16
}

func NewHapticFrame(t entities.FrameType, data []byte) *HapticFrame {
	return &HapticFrame{
		Type: t,
		Data: data,
	}
}

// ReadNextFrame reads a single frame from the stream.
// It returns an error if the frame is invalid or the stream is closed.
// It includes the frame type and length in the returned frame.
func ReadNextFrame(s io.Reader) (*HapticFrame, error) {
	frame := &HapticFrame{}

	// Read the frame type
	err := frame.readType(s)
	if err != nil {
		return nil, err
	}

	// Read the frame length
	err = frame.readLength(s)
	if err != nil {
		return nil, err
	}

	// Read the frame data
	buf, n, err := readN(s, int(frame.dataLength))
	if err != nil {
		return nil, err
	}

	// Check that the frame length matches the number of bytes read
	if n == int(frame.dataLength) {
		frame.Data = buf
		return frame, nil
	}

	return nil, ErrInvalidLength(n)
}

// readType reads the frame type from the stream.
// The type is always the first byte of the frame.
func (f *HapticFrame) readType(s io.Reader) error {
	buf, n, err := readN(s, 1)
	if err != nil {
		return err
	}

	if n == 1 {
		ft := entities.FrameType(buf[0])
		if ft != entities.FrameType_UNKNOWN {
			f.Type = ft
			return nil
		}
	}

	return ErrUnknownFrameType
}

// Length returns the length of the frame data, excluding the header.
func (f *HapticFrame) Length() uint16 {
	if f.dataLength == 0 {
		f.dataLength = uint16(len(f.Data))
	}
	return f.dataLength
}

// readLength reads the frame length from the stream.
// The length is always the second and third byte of the frame.
func (f *HapticFrame) readLength(s io.Reader) error {
	buf, _, err := readN(s, 2)
	if err != nil {
		return err
	}

	// Check that the length is valid
	f.dataLength = binary.LittleEndian.Uint16(buf) - headerLength
	if f.dataLength <= maxDataLength {
		return nil
	}

	return ErrInvalidLength(int(f.dataLength))
}

// WriteFrame writes a single frame to the stream.
// It returns an error if the frame is invalid or the stream is closed.
// It prepends the frame type and length to the frame data.
func (f *HapticFrame) WriteFrame(w io.Writer) error {
	length := uint16(len(f.Data) + headerLength)
	if length == headerLength || length > maxDataLength {
		return ErrInvalidLength(int(length))
	}

	buf := make([]byte, length)
	buf[0] = byte(f.Type)

	binary.LittleEndian.PutUint16(buf[1:], length)
	copy(buf[3:], f.Data)

	// Write the whole frame at once
	_, err := w.Write(buf)
	if err != nil {
		return err
	}

	return nil
}