proto/proto.go

   1 //
   2 // Copyright (C) 2014 Sebastian 'tokkee' Harl <sh@tokkee.org>
   3 // All rights reserved.
   4 //
   5 // Redistribution and use in source and binary forms, with or without
   6 // modification, are permitted provided that the following conditions
   7 // are met:
   8 // 1. Redistributions of source code must retain the above copyright
   9 //    notice, this list of conditions and the following disclaimer.
  10 // 2. Redistributions in binary form must reproduce the above copyright
  11 //    notice, this list of conditions and the following disclaimer in the
  12 //    documentation and/or other materials provided with the distribution.
  13 //
  14 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  15 // ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  16 // TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  17 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
  18 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  19 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  20 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  21 // OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  22 // WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  23 // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  24 // ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25
  26 // Package proto provides helper functions for using the SysDB front-end
  27 // protocol. That's the protocol used for communication between a client and a
  28 // SysDB server instance.
  29 package proto
  30
  31 import (
  32         "encoding/binary"
  33         "encoding/json"
  34         "fmt"
  35         "io"
  36         "strings"
  37 )
  38
  39 // Network byte order.
  40 var nbo = binary.BigEndian
  41
  42 // A Status represents the type of a message. The message type describes the
  43 // current status or state of a connection depending on the context.
  44 type Status uint32
  45
  46 const (
  47         // ConnectionOK indicates that a command was successful.
  48         ConnectionOK = Status(0)
  49         // ConnectionError indicates that a command has failed.
  50         ConnectionError = Status(1)
  51         // ConnectionLog indicates an (asynchronous) log message.
  52         ConnectionLog = Status(2)
  53
  54         // ConnectionData indicates a successful query returning data.
  55         ConnectionData = Status(100)
  56 )
  57
  58 const (
  59         // ConnectionIdle is the internal state for idle connections.
  60         ConnectionIdle = Status(0)
  61         // ConnectionPing is the state requesting a connection check.
  62         ConnectionPing = Status(1)
  63         // ConnectionStartup is the state requesting the setup of a client
  64         // connection.
  65         ConnectionStartup = Status(2)
  66
  67         // ConnectionQuery is the state requesting the execution of a query in the
  68         // server.
  69         ConnectionQuery = Status(3)
  70         // ConnectionFetch is the state requesting the execution of the 'FETCH'
  71         // command in the server.
  72         ConnectionFetch = Status(4)
  73         // ConnectionList is the state requesting the execution of the 'LIST'
  74         // command in the server.
  75         ConnectionList = Status(5)
  76         // ConnectionLookup is the state requesting the execution of the 'LOOKUP'
  77         // command in the server.
  78         ConnectionLookup = Status(6)
  79         // ConnectionTimeseries is the state requesting the execution of the
  80         // 'TIMESERIES' command in the server.
  81         ConnectionTimeseries = Status(7)
  82
  83         // ConnectionMatcher is the internal state for parsing matchers.
  84         ConnectionMatcher = Status(100)
  85         // ConnectionExpr is the internal state for parsing expressions.
  86         ConnectionExpr = Status(101)
  87
  88         // ConnectionServerVersion is the state requesting the server version.
  89         ConnectionServerVersion = Status(1000)
  90 )
  91
  92 // The DataType describes the type of data in a ConnectionData message.
  93 type DataType int
  94
  95 const (
  96         // A HostList can be unmarshaled to []sysdb.Host.
  97         HostList DataType = iota
  98         // A Host can be unmarshaled to sysdb.Host.
  99         Host
 100         // A Timeseries can be unmarshaled to sysdb.Timeseries.
 101         Timeseries
 102 )
 103
 104 // A Message represents a raw message of the SysDB front-end protocol.
 105 type Message struct {
 106         Type Status
 107         Raw  []byte
 108 }
 109
 110 // Read reads a raw message encoded in the SysDB wire format from r. The
 111 // function parses the header but the raw body of the message will still be
 112 // encoded in the wire format.
 113 //
 114 // The reader has to be in blocking mode. Otherwise, the client and server
 115 // will be out of sync after reading a partial message and cannot recover from
 116 // that.
 117 func Read(r io.Reader) (*Message, error) {
 118         var header [8]byte
 119         if _, err := io.ReadFull(r, header[:]); err != nil {
 120                 return nil, err
 121         }
 122
 123         typ := nbo.Uint32(header[:4])
 124         l := nbo.Uint32(header[4:])
 125         msg := make([]byte, l)
 126         if _, err := io.ReadFull(r, msg); err != nil {
 127                 return nil, err
 128         }
 129
 130         return &Message{Status(typ), msg}, nil
 131 }
 132
 133 // Write writes a raw message to w. The raw body of m has to be encoded in the
 134 // SysDB wire format. The function adds the right header to the message.
 135 //
 136 // The writer has to be in blocking mode. Otherwise, the client and server
 137 // will be out of sync after writing a partial message and cannot recover from
 138 // that.
 139 func Write(w io.Writer, m *Message) error {
 140         var header [8]byte
 141         nbo.PutUint32(header[:4], uint32(m.Type))
 142         nbo.PutUint32(header[4:], uint32(len(m.Raw)))
 143
 144         if _, err := io.WriteString(w, string(header[:])); err != nil {
 145                 return err
 146         }
 147         if _, err := io.WriteString(w, string(m.Raw)); err != nil {
 148                 return err
 149         }
 150         return nil
 151 }
 152
 153 // DataType determines the type of data in a ConnectionData message.
 154 func (m Message) DataType() (DataType, error) {
 155         if m.Type != ConnectionData {
 156                 return 0, fmt.Errorf("message is not of type DATA")
 157         }
 158
 159         typ := nbo.Uint32(m.Raw[:4])
 160         switch Status(typ) {
 161         case ConnectionList, ConnectionLookup:
 162                 return HostList, nil
 163         case ConnectionFetch:
 164                 return Host, nil
 165         case ConnectionTimeseries:
 166                 return Timeseries, nil
 167         }
 168         return 0, fmt.Errorf("unknown DATA type %d", typ)
 169 }
 170
 171 // Unmarshal parses the raw body of m and stores the result in the value
 172 // pointed to by v which has to match the type of the message and its data.
 173 func Unmarshal(m *Message, v interface{}) error {
 174         if m.Type != ConnectionData {
 175                 return fmt.Errorf("unmarshaling message of type %d not supported", m.Type)
 176         }
 177         if len(m.Raw) == 0 { // empty command
 178                 return nil
 179         } else if len(m.Raw) < 4 {
 180                 return fmt.Errorf("DATA message body too short")
 181         }
 182         return json.Unmarshal(m.Raw[4:], v)
 183 }
 184
 185 // EscapeString returns the quoted and escaped string s suitable for use
 186 // in a query.
 187 func EscapeString(s string) string {
 188         // Currently, the server only handles double-quotes.
 189         // Backslashes do not serve any special purpose.
 190         return "'" + strings.Replace(s, "'", "''", -1) + "'"
 191 }
 192
 193 // vim: set tw=78 sw=4 sw=4 noexpandtab :