-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Cassandra CQL binary protocol.
--   
--   Implementation of Cassandra's CQL Binary Protocol <a>Version 2</a> and
--   <a>Version 3</a>.
--   
--   It provides encoding and decoding functionality as well as
--   representations of the various protocol related types.
--   
--   Thus it can serve as a building block for writing Cassandra drivers,
--   such as <a>cql-io</a>.
@package cql
@version 3.0.7


-- | Like <a>Database.CQL.Protocol</a> but exports the whole encode/decode
--   machinery for all types.
module Database.CQL.Protocol.Internal

-- | A type that can be converted from and to some CQL <a>Value</a>.
--   
--   This type-class is used to map custom types to Cassandra data-types.
--   For example:
--   
--   <pre>
--   newtype MyType = MyType Int32
--   
--   instance Cql MyType where
--       ctype              = Tagged IntColumn
--       toCql (MyType i)   = CqlInt i
--       fromCql (CqlInt i) = Right (MyType i)
--       fromCql _          = Left "Expected CqlInt"
--   </pre>
class Cql a

-- | the column-type of <tt>a</tt>
ctype :: Cql a => Tagged a ColumnType

-- | map <tt>a</tt> to some CQL data-type
toCql :: Cql a => a -> Value

-- | map a CQL value back to <tt>a</tt>
fromCql :: Cql a => Value -> Either String a
newtype Keyspace
Keyspace :: Text -> Keyspace
[unKeyspace] :: Keyspace -> Text
newtype Table
Table :: Text -> Table
[unTable] :: Table -> Text

-- | Opaque token passed to the server to continue result paging.
newtype PagingState
PagingState :: ByteString -> PagingState
[unPagingState] :: PagingState -> ByteString

-- | ID representing a prepared query.
newtype QueryId k a b
QueryId :: ByteString -> QueryId k a b
[unQueryId] :: QueryId k a b -> ByteString
newtype QueryString k a b
QueryString :: Text -> QueryString k a b
[unQueryString] :: QueryString k a b -> Text

-- | CQL binary protocol version.
data Version

-- | version 2
V2 :: Version

-- | version 3
V3 :: Version

-- | The CQL version (not the binary protocol version).
data CqlVersion
Cqlv300 :: CqlVersion
CqlVersion :: !Text -> CqlVersion
data CompressionAlgorithm
Snappy :: CompressionAlgorithm
LZ4 :: CompressionAlgorithm
None :: CompressionAlgorithm
data Compression
Compression :: !CompressionAlgorithm -> (ByteString -> Maybe ByteString) -> (ByteString -> Maybe ByteString) -> Compression
[algorithm] :: Compression -> !CompressionAlgorithm
[shrink] :: Compression -> ByteString -> Maybe ByteString
[expand] :: Compression -> ByteString -> Maybe ByteString
noCompression :: Compression

-- | Consistency level.
data Consistency
Any :: Consistency
One :: Consistency
Two :: Consistency
Three :: Consistency
Quorum :: Consistency
All :: Consistency
LocalQuorum :: Consistency
EachQuorum :: Consistency
Serial :: Consistency
LocalOne :: Consistency
LocalSerial :: Consistency

-- | An opcode is a tag to distinguish protocol frame bodies.
data OpCode
OcError :: OpCode
OcStartup :: OpCode
OcReady :: OpCode
OcAuthenticate :: OpCode
OcOptions :: OpCode
OcSupported :: OpCode
OcQuery :: OpCode
OcResult :: OpCode
OcPrepare :: OpCode
OcExecute :: OpCode
OcRegister :: OpCode
OcEvent :: OpCode
OcBatch :: OpCode
OcAuthChallenge :: OpCode
OcAuthResponse :: OpCode
OcAuthSuccess :: OpCode

-- | The type of a single CQL column.
data ColumnType
CustomColumn :: !Text -> ColumnType
AsciiColumn :: ColumnType
BigIntColumn :: ColumnType
BlobColumn :: ColumnType
BooleanColumn :: ColumnType
CounterColumn :: ColumnType
DecimalColumn :: ColumnType
DoubleColumn :: ColumnType
FloatColumn :: ColumnType
IntColumn :: ColumnType
TextColumn :: ColumnType
TimestampColumn :: ColumnType
UuidColumn :: ColumnType
VarCharColumn :: ColumnType
VarIntColumn :: ColumnType
TimeUuidColumn :: ColumnType
InetColumn :: ColumnType
MaybeColumn :: !ColumnType -> ColumnType
ListColumn :: !ColumnType -> ColumnType
SetColumn :: !ColumnType -> ColumnType
MapColumn :: !ColumnType -> !ColumnType -> ColumnType
TupleColumn :: [ColumnType] -> ColumnType
UdtColumn :: !Keyspace -> !Text -> [(Text, ColumnType)] -> ColumnType
newtype Ascii
Ascii :: Text -> Ascii
[fromAscii] :: Ascii -> Text
newtype Blob
Blob :: ByteString -> Blob
[fromBlob] :: Blob -> ByteString
newtype Counter
Counter :: Int64 -> Counter
[fromCounter] :: Counter -> Int64
newtype TimeUuid
TimeUuid :: UUID -> TimeUuid
[fromTimeUuid] :: TimeUuid -> UUID
newtype Set a
Set :: [a] -> Set a
[fromSet] :: Set a -> [a]
newtype Map a b
Map :: [(a, b)] -> Map a b
[fromMap] :: Map a b -> [(a, b)]

-- | A CQL value. The various constructors correspond to CQL data-types for
--   individual columns in Cassandra.
data Value
CqlCustom :: !ByteString -> Value
CqlBoolean :: !Bool -> Value
CqlInt :: !Int32 -> Value
CqlBigInt :: !Int64 -> Value
CqlVarInt :: !Integer -> Value
CqlFloat :: !Float -> Value
CqlDecimal :: !Decimal -> Value
CqlDouble :: !Double -> Value
CqlText :: !Text -> Value
CqlInet :: !IP -> Value
CqlUuid :: !UUID -> Value
CqlTimestamp :: !Int64 -> Value
CqlAscii :: !Text -> Value
CqlBlob :: !ByteString -> Value
CqlCounter :: !Int64 -> Value
CqlTimeUuid :: !UUID -> Value
CqlMaybe :: (Maybe Value) -> Value
CqlList :: [Value] -> Value
CqlSet :: [Value] -> Value
CqlMap :: [(Value, Value)] -> Value

-- | binary protocol version &gt;= 3
CqlTuple :: [Value] -> Value

-- | binary protocol version &gt;= 3
CqlUdt :: [(Text, Value)] -> Value

-- | Tag some value with a phantom type.
newtype Tagged a b
Tagged :: b -> Tagged a b
[untag] :: Tagged a b -> b
retag :: Tagged a c -> Tagged b c
data R
data W
data S

-- | Protocol frame header.
data Header
Header :: !HeaderType -> !Version -> !Flags -> !StreamId -> !OpCode -> !Length -> Header
[headerType] :: Header -> !HeaderType
[version] :: Header -> !Version
[flags] :: Header -> !Flags
[streamId] :: Header -> !StreamId
[opCode] :: Header -> !OpCode
[bodyLength] :: Header -> !Length
data HeaderType

-- | A request frame header.
RqHeader :: HeaderType

-- | A response frame header.
RsHeader :: HeaderType

-- | Deserialise a frame header using the version specific decoding format.
header :: Version -> ByteString -> Either String Header
encodeHeader :: Version -> HeaderType -> Flags -> StreamId -> OpCode -> Length -> PutM ()
decodeHeader :: Version -> Get Header

-- | The type denoting a protocol frame length.
newtype Length
Length :: Int32 -> Length
[lengthRepr] :: Length -> Int32
encodeLength :: Putter Length
decodeLength :: Get Length

-- | Streams allow multiplexing of requests over a single communication
--   channel. The <a>StreamId</a> correlates <tt>Request</tt>s with
--   <tt>Response</tt>s.
data StreamId

-- | Create a StreamId from the given integral value. In version 2, a
--   StreamId is an <a>Int8</a> and in version 3 an <a>Int16</a>.
mkStreamId :: Integral i => i -> StreamId

-- | Convert the stream ID to an integer.
fromStreamId :: StreamId -> Int
encodeStreamId :: Version -> Putter StreamId
decodeStreamId :: Version -> Get StreamId

-- | Type representing header flags. Flags form a monoid and can be used as
--   in <tt>compress &lt;&gt; tracing &lt;&gt; mempty</tt>.
data Flags

-- | Compression flag. If set, the frame body is compressed.
compress :: Flags

-- | Tracing flag. If a request support tracing and the tracing flag was
--   set, the response to this request will have the tracing flag set and
--   contain tracing information.
tracing :: Flags

-- | Check if a particular flag is present.
isSet :: Flags -> Flags -> Bool
encodeFlags :: Putter Flags
decodeFlags :: Get Flags

-- | The type corresponding to the protocol request frame.
--   
--   The type parameter <tt>k</tt> denotes the kind of request. It is
--   present to allow distinguishing read operations from write operations.
--   Use <a>R</a> for read, <a>W</a> for write and <a>S</a> for schema
--   related operations.
--   
--   <tt>a</tt> represents the argument type and <tt>b</tt> the return type
--   of this request.
data Request k a b
RqStartup :: !Startup -> Request k a b
RqOptions :: !Options -> Request k a b
RqRegister :: !Register -> Request k a b
RqBatch :: !Batch -> Request k a b
RqAuthResp :: !AuthResponse -> Request k a b
RqPrepare :: !(Prepare k a b) -> Request k a b
RqQuery :: !(Query k a b) -> Request k a b
RqExecute :: !(Execute k a b) -> Request k a b

-- | Serialise the given request, optionally using compression. The result
--   is either an error description in case of failure or a binary protocol
--   frame, including <a>Header</a>, <a>Length</a> and body.
pack :: Tuple a => Version -> Compression -> Bool -> StreamId -> Request k a b -> Either String ByteString
encodeRequest :: Tuple a => Version -> Putter (Request k a b)

-- | Get the protocol <a>OpCode</a> corresponding to the given
--   <a>Request</a>.
getOpCode :: Request k a b -> OpCode

-- | An options request, send prior to <a>Startup</a> to request the
--   server's startup options.
data Options
Options :: Options
encodeOptions :: Putter Options

-- | A startup request which is used when initialising a connection to the
--   server. It specifies the CQL version to use and optionally the
--   compression algorithm.
data Startup
Startup :: !CqlVersion -> !CompressionAlgorithm -> Startup
encodeStartup :: Putter Startup

-- | A request send in response to a previous authentication challenge.
newtype AuthResponse
AuthResponse :: ByteString -> AuthResponse
encodeAuthResponse :: Putter AuthResponse

-- | Register's the connection this request is made through, to receive
--   server events.
newtype Register
Register :: [EventType] -> Register

-- | Event types to register.
data EventType

-- | events related to change in the cluster topology
TopologyChangeEvent :: EventType

-- | events related to change of node status
StatusChangeEvent :: EventType

-- | events related to schema change
SchemaChangeEvent :: EventType
encodeRegister :: Putter Register
encodeEventType :: Putter EventType

-- | A CQL query (select, insert, etc.).
data Query k a b
Query :: !(QueryString k a b) -> !(QueryParams a) -> Query k a b

-- | Query parameters.
data QueryParams a
QueryParams :: !Consistency -> !Bool -> a -> Maybe Int32 -> Maybe PagingState -> Maybe SerialConsistency -> QueryParams a

-- | consistency leven to use
[consistency] :: QueryParams a -> !Consistency

-- | skip metadata in response
[skipMetaData] :: QueryParams a -> !Bool

-- | query arguments
[values] :: QueryParams a -> a

-- | desired result set size
[pageSize] :: QueryParams a -> Maybe Int32
[queryPagingState] :: QueryParams a -> Maybe PagingState
[serialConsistency] :: QueryParams a -> Maybe SerialConsistency

-- | Consistency level for the serial phase of conditional updates.
data SerialConsistency
SerialConsistency :: SerialConsistency
LocalSerialConsistency :: SerialConsistency
encodeQuery :: Tuple a => Version -> Putter (Query k a b)
encodeQueryParams :: Tuple a => Version -> Putter (QueryParams a)

-- | Allows executing a list of queries (prepared or not) as a batch.
data Batch
Batch :: !BatchType -> [BatchQuery] -> !Consistency -> Maybe SerialConsistency -> Batch
[batchType] :: Batch -> !BatchType
[batchQuery] :: Batch -> [BatchQuery]
[batchConsistency] :: Batch -> !Consistency
[batchSerialConsistency] :: Batch -> Maybe SerialConsistency

-- | A GADT to unify queries and prepared queries both of which can be used
--   in batch requests.
data BatchQuery
BatchQuery :: !(QueryString W a b) -> !a -> BatchQuery
BatchPrepared :: !(QueryId W a b) -> !a -> BatchQuery
data BatchType

-- | default, uses a batch log for atomic application
BatchLogged :: BatchType

-- | skip the batch log
BatchUnLogged :: BatchType

-- | used for batched counter updates
BatchCounter :: BatchType
encodeBatch :: Version -> Putter Batch
encodeBatchType :: Putter BatchType
encodeBatchQuery :: Version -> Putter BatchQuery

-- | Prepare a query for later execution (cf. <a>Execute</a>).
newtype Prepare k a b
Prepare :: (QueryString k a b) -> Prepare k a b
encodePrepare :: Putter (Prepare k a b)

-- | Executes a prepared query.
data Execute k a b
Execute :: !(QueryId k a b) -> !(QueryParams a) -> Execute k a b
encodeExecute :: Tuple a => Version -> Putter (Execute k a b)

-- | The type corresponding to the protocol response frame.
--   
--   The type parameter <tt>k</tt> denotes the kind of response. It is
--   present to allow distinguishing read operations from write operations.
--   Use <a>R</a> for read, <a>W</a> for write and <a>S</a> for schema
--   related operations.
--   
--   <tt>a</tt> represents the argument type and <tt>b</tt> the return type
--   of this response.
data Response k a b
RsError :: (Maybe UUID) -> !Error -> Response k a b
RsReady :: (Maybe UUID) -> !Ready -> Response k a b
RsAuthenticate :: (Maybe UUID) -> !Authenticate -> Response k a b
RsAuthChallenge :: (Maybe UUID) -> !AuthChallenge -> Response k a b
RsAuthSuccess :: (Maybe UUID) -> !AuthSuccess -> Response k a b
RsSupported :: (Maybe UUID) -> !Supported -> Response k a b
RsResult :: (Maybe UUID) -> !(Result k a b) -> Response k a b
RsEvent :: (Maybe UUID) -> !Event -> Response k a b

-- | Deserialise a <a>Response</a> from the given <a>ByteString</a>.
unpack :: (Tuple a, Tuple b) => Compression -> Header -> ByteString -> Either String (Response k a b)

-- | The server is ready to process queries. Response of a <tt>Startup</tt>
--   request.
data Ready
Ready :: Ready
decodeReady :: Get Ready

-- | The server requires authentication.
newtype Authenticate
Authenticate :: Text -> Authenticate

-- | A server-send authentication challenge.
newtype AuthChallenge
AuthChallenge :: (Maybe ByteString) -> AuthChallenge

-- | Indicates the success of an authentication phase.
newtype AuthSuccess
AuthSuccess :: (Maybe ByteString) -> AuthSuccess
decodeAuthenticate :: Get Authenticate
decodeAuthChallenge :: Get AuthChallenge
decodeAuthSuccess :: Get AuthSuccess

-- | Query response.
data Result k a b
VoidResult :: Result k a b
RowsResult :: !MetaData -> [b] -> Result k a b
SetKeyspaceResult :: !Keyspace -> Result k a b
PreparedResult :: !(QueryId k a b) -> !MetaData -> !MetaData -> Result k a b
SchemaChangeResult :: !SchemaChange -> Result k a b

-- | Part of a <tt>RowsResult</tt>. Describes the result set.
data MetaData
MetaData :: !Int32 -> Maybe PagingState -> [ColumnSpec] -> MetaData
[columnCount] :: MetaData -> !Int32
[pagingState] :: MetaData -> Maybe PagingState
[columnSpecs] :: MetaData -> [ColumnSpec]

-- | The column specification. Part of <a>MetaData</a> unless
--   <tt>skipMetaData</tt> in <tt>QueryParams</tt> was True.
data ColumnSpec
ColumnSpec :: !Keyspace -> !Table -> !Text -> !ColumnType -> ColumnSpec
[keyspace] :: ColumnSpec -> !Keyspace
[table] :: ColumnSpec -> !Table
[columnName] :: ColumnSpec -> !Text
[columnType] :: ColumnSpec -> !ColumnType
decodeResult :: (Tuple a, Tuple b) => Version -> Get (Result k a b)
decodeMetaData :: Get MetaData

-- | The startup options supported by the server. Response of an
--   <tt>Options</tt> request.
data Supported
Supported :: [CompressionAlgorithm] -> [CqlVersion] -> Supported
decodeSupported :: Get Supported

-- | Messages send by the server without request, if the connection has
--   been <tt>Register</tt>ed to receive such events.
data Event
TopologyEvent :: !TopologyChange -> !SockAddr -> Event
StatusEvent :: !StatusChange -> !SockAddr -> Event
SchemaEvent :: !SchemaChange -> Event
data TopologyChange
NewNode :: TopologyChange
RemovedNode :: TopologyChange
data SchemaChange
SchemaCreated :: !Change -> SchemaChange
SchemaUpdated :: !Change -> SchemaChange
SchemaDropped :: !Change -> SchemaChange
data StatusChange
Up :: StatusChange
Down :: StatusChange
data Change
KeyspaceChange :: !Keyspace -> Change
TableChange :: !Keyspace -> !Table -> Change
TypeChange :: !Keyspace -> !Text -> Change
decodeSchemaChange :: Version -> Get SchemaChange
decodeChange :: Version -> Get Change
decodeEvent :: Version -> Get Event
decodeTopologyChange :: Get TopologyChange
decodeStatusChange :: Get StatusChange

-- | Error response.
data Error
AlreadyExists :: !Text -> !Keyspace -> !Table -> Error
BadCredentials :: !Text -> Error
ConfigError :: !Text -> Error
Invalid :: !Text -> Error
IsBootstrapping :: !Text -> Error
Overloaded :: !Text -> Error
ProtocolError :: !Text -> Error
ServerError :: !Text -> Error
SyntaxError :: !Text -> Error
TruncateError :: !Text -> Error
Unauthorized :: !Text -> Error
Unprepared :: !Text -> !ByteString -> Error
Unavailable :: !Text -> !Consistency -> !Int32 -> !Int32 -> Error
[unavailMessage] :: Error -> !Text
[unavailConsistency] :: Error -> !Consistency
[unavailNumRequired] :: Error -> !Int32
[unavailNumAlive] :: Error -> !Int32
ReadTimeout :: !Text -> !Consistency -> !Int32 -> !Int32 -> !Bool -> Error
[rTimeoutMessage] :: Error -> !Text
[rTimeoutConsistency] :: Error -> !Consistency
[rTimeoutNumAck] :: Error -> !Int32
[rTimeoutNumRequired] :: Error -> !Int32
[rTimeoutDataPresent] :: Error -> !Bool
WriteTimeout :: !Text -> !Consistency -> !Int32 -> !Int32 -> !WriteType -> Error
[wTimeoutMessage] :: Error -> !Text
[wTimeoutConsistency] :: Error -> !Consistency
[wTimeoutNumAck] :: Error -> !Int32
[wTimeoutNumRequired] :: Error -> !Int32
[wTimeoutWriteType] :: Error -> !WriteType
data WriteType
WriteSimple :: WriteType
WriteBatch :: WriteType
WriteBatchLog :: WriteType
WriteUnloggedBatch :: WriteType
WriteCounter :: WriteType
decodeError :: Get Error
decodeWriteType :: Get WriteType
class PrivateTuple a => Tuple a
count :: PrivateTuple a => Tagged a Int
check :: PrivateTuple a => Tagged a ([ColumnType] -> [ColumnType])
tuple :: PrivateTuple a => Version -> [ColumnType] -> Get a
store :: PrivateTuple a => Version -> Putter a

-- | A row is a vector of <a>Value</a>s.
data Row
mkRow :: [(Value, ColumnType)] -> Row

-- | Convert a row element.
fromRow :: Cql a => Int -> Row -> Either String a
columnTypes :: Row -> [ColumnType]
rowLength :: Row -> Int

-- | Record/Tuple conversion. For example:
--   
--   <pre>
--   data Peer = Peer
--       { peerAddr :: IP
--       , peerRPC  :: IP
--       , peerDC   :: Text
--       , peerRack :: Text
--       } deriving Show
--   
--   recordInstance ''Peer
--   
--   map asRecord &lt;$&gt; performQuery "SELECT peer, rpc_address, data_center, rack FROM system.peers"
--   </pre>
--   
--   The generated type-class instance maps between record and tuple
--   constructors:
--   
--   <pre>
--   type instance TupleType Peer = (IP, IP, Text, Text)
--   
--   instance Record Peer where
--       asTuple (Peer a b c d) = (a, b, c, d)
--       asRecord (a, b, c, d)  = Peer a b c d
--   </pre>
class Record a
asTuple :: Record a => a -> TupleType a
asRecord :: Record a => TupleType a -> a
recordInstance :: Name -> Q [Dec]
encodeByte :: Putter Word8
decodeByte :: Get Word8
encodeSignedByte :: Putter Int8
decodeSignedByte :: Get Int8
encodeShort :: Putter Word16
decodeShort :: Get Word16
encodeSignedShort :: Putter Int16
decodeSignedShort :: Get Int16
encodeInt :: Putter Int32
decodeInt :: Get Int32
encodeString :: Putter Text
decodeString :: Get Text
encodeLongString :: Putter Text
decodeLongString :: Get Text
encodeBytes :: Putter ByteString
decodeBytes :: Get (Maybe ByteString)
encodeShortBytes :: Putter ByteString
decodeShortBytes :: Get ByteString
encodeUUID :: Putter UUID
decodeUUID :: Get UUID
encodeList :: Putter [Text]
decodeList :: Get [Text]
encodeMap :: Putter [(Text, Text)]
decodeMap :: Get [(Text, Text)]
encodeMultiMap :: Putter [(Text, [Text])]
decodeMultiMap :: Get [(Text, [Text])]
encodeSockAddr :: Putter SockAddr
decodeSockAddr :: Get SockAddr
encodeConsistency :: Putter Consistency
decodeConsistency :: Get Consistency
encodeOpCode :: Putter OpCode
decodeOpCode :: Get OpCode
encodeColumnType :: Putter ColumnType
decodeColumnType :: Get ColumnType
encodePagingState :: Putter PagingState
decodePagingState :: Get (Maybe PagingState)
decodeKeyspace :: Get Keyspace
decodeTable :: Get Table
decodeQueryId :: Get (QueryId k a b)
putValue :: Version -> Putter Value
getValue :: Version -> ColumnType -> Get Value


-- | The CQL native protocol is a binary frame-based protocol where each
--   frame has a <a>Header</a>, a <a>Length</a> and a body. The protocol
--   distinguishes <a>Request</a>s and <a>Response</a>s.
--   
--   Some usage examples:
--   
--   <b>Constructing and Serialising a Request</b>
--   
--   <pre>
--   let q = QueryString "select peer from system.peers where data_center = ? and rack = ?"
--       p = QueryParams One False ("uk-1", "r-0") Nothing Nothing Nothing
--       r = RqQuery (Query q p :: Query R (Text, Text) (Identity IP))
--       i = mkStreamId 0
--   in pack V3 noCompression False i r
--   </pre>
--   
--   <b>Deserialising a Response</b>
--   
--   <pre>
--   -- assuming <tt>bh</tt> contains the raw header byte string and <tt>bb</tt> the raw
--   -- body byte string.
--   case header V3 bh of
--       Left  e -&gt; ...
--       Right h -&gt; unpack noCompression h bb
--   </pre>
--   
--   <b>A generic query processing function</b>
--   
--   <pre>
--   query :: (Tuple a, Tuple b) =&gt; Version -&gt; Socket -&gt; QueryString k a b -&gt; QueryParams a -&gt; IO (Response k a b)
--   query v s q p = do
--       let i = mkStreamId 0
--       sendToServer s (pack v noCompression False i (RqQuery (Query q p)))
--       b &lt;- recv (if v == V3 then 9 else 8) s
--       h &lt;- either (throwIO . MyException) return (header v b)
--       when (headerType h == RqHeader) $
--           throwIO UnexpectedRequestHeader
--       let len = lengthRepr (bodyLength h)
--       x &lt;- recv (fromIntegral len) s
--       case unpack noCompression h x of
--           Left e              -&gt; throwIO $ AnotherException e
--           Right (RsError _ e) -&gt; throwIO e
--           Right response      -&gt; return response
--   </pre>
module Database.CQL.Protocol

-- | A type that can be converted from and to some CQL <a>Value</a>.
--   
--   This type-class is used to map custom types to Cassandra data-types.
--   For example:
--   
--   <pre>
--   newtype MyType = MyType Int32
--   
--   instance Cql MyType where
--       ctype              = Tagged IntColumn
--       toCql (MyType i)   = CqlInt i
--       fromCql (CqlInt i) = Right (MyType i)
--       fromCql _          = Left "Expected CqlInt"
--   </pre>
class Cql a

-- | the column-type of <tt>a</tt>
ctype :: Cql a => Tagged a ColumnType

-- | map <tt>a</tt> to some CQL data-type
toCql :: Cql a => a -> Value

-- | map a CQL value back to <tt>a</tt>
fromCql :: Cql a => Value -> Either String a
newtype Keyspace
Keyspace :: Text -> Keyspace
[unKeyspace] :: Keyspace -> Text
newtype Table
Table :: Text -> Table
[unTable] :: Table -> Text

-- | Opaque token passed to the server to continue result paging.
newtype PagingState
PagingState :: ByteString -> PagingState
[unPagingState] :: PagingState -> ByteString

-- | ID representing a prepared query.
newtype QueryId k a b
QueryId :: ByteString -> QueryId k a b
[unQueryId] :: QueryId k a b -> ByteString
newtype QueryString k a b
QueryString :: Text -> QueryString k a b
[unQueryString] :: QueryString k a b -> Text

-- | CQL binary protocol version.
data Version

-- | version 2
V2 :: Version

-- | version 3
V3 :: Version

-- | The CQL version (not the binary protocol version).
data CqlVersion
Cqlv300 :: CqlVersion
CqlVersion :: !Text -> CqlVersion
data CompressionAlgorithm
Snappy :: CompressionAlgorithm
LZ4 :: CompressionAlgorithm
None :: CompressionAlgorithm
data Compression
Compression :: !CompressionAlgorithm -> (ByteString -> Maybe ByteString) -> (ByteString -> Maybe ByteString) -> Compression
[algorithm] :: Compression -> !CompressionAlgorithm
[shrink] :: Compression -> ByteString -> Maybe ByteString
[expand] :: Compression -> ByteString -> Maybe ByteString
noCompression :: Compression

-- | Consistency level.
data Consistency
Any :: Consistency
One :: Consistency
Two :: Consistency
Three :: Consistency
Quorum :: Consistency
All :: Consistency
LocalQuorum :: Consistency
EachQuorum :: Consistency
Serial :: Consistency
LocalOne :: Consistency
LocalSerial :: Consistency

-- | An opcode is a tag to distinguish protocol frame bodies.
data OpCode
OcError :: OpCode
OcStartup :: OpCode
OcReady :: OpCode
OcAuthenticate :: OpCode
OcOptions :: OpCode
OcSupported :: OpCode
OcQuery :: OpCode
OcResult :: OpCode
OcPrepare :: OpCode
OcExecute :: OpCode
OcRegister :: OpCode
OcEvent :: OpCode
OcBatch :: OpCode
OcAuthChallenge :: OpCode
OcAuthResponse :: OpCode
OcAuthSuccess :: OpCode

-- | The type of a single CQL column.
data ColumnType
CustomColumn :: !Text -> ColumnType
AsciiColumn :: ColumnType
BigIntColumn :: ColumnType
BlobColumn :: ColumnType
BooleanColumn :: ColumnType
CounterColumn :: ColumnType
DecimalColumn :: ColumnType
DoubleColumn :: ColumnType
FloatColumn :: ColumnType
IntColumn :: ColumnType
TextColumn :: ColumnType
TimestampColumn :: ColumnType
UuidColumn :: ColumnType
VarCharColumn :: ColumnType
VarIntColumn :: ColumnType
TimeUuidColumn :: ColumnType
InetColumn :: ColumnType
MaybeColumn :: !ColumnType -> ColumnType
ListColumn :: !ColumnType -> ColumnType
SetColumn :: !ColumnType -> ColumnType
MapColumn :: !ColumnType -> !ColumnType -> ColumnType
TupleColumn :: [ColumnType] -> ColumnType
UdtColumn :: !Keyspace -> !Text -> [(Text, ColumnType)] -> ColumnType
newtype Ascii
Ascii :: Text -> Ascii
[fromAscii] :: Ascii -> Text
newtype Blob
Blob :: ByteString -> Blob
[fromBlob] :: Blob -> ByteString
newtype Counter
Counter :: Int64 -> Counter
[fromCounter] :: Counter -> Int64
newtype TimeUuid
TimeUuid :: UUID -> TimeUuid
[fromTimeUuid] :: TimeUuid -> UUID
newtype Set a
Set :: [a] -> Set a
[fromSet] :: Set a -> [a]
newtype Map a b
Map :: [(a, b)] -> Map a b
[fromMap] :: Map a b -> [(a, b)]

-- | A CQL value. The various constructors correspond to CQL data-types for
--   individual columns in Cassandra.
data Value
CqlCustom :: !ByteString -> Value
CqlBoolean :: !Bool -> Value
CqlInt :: !Int32 -> Value
CqlBigInt :: !Int64 -> Value
CqlVarInt :: !Integer -> Value
CqlFloat :: !Float -> Value
CqlDecimal :: !Decimal -> Value
CqlDouble :: !Double -> Value
CqlText :: !Text -> Value
CqlInet :: !IP -> Value
CqlUuid :: !UUID -> Value
CqlTimestamp :: !Int64 -> Value
CqlAscii :: !Text -> Value
CqlBlob :: !ByteString -> Value
CqlCounter :: !Int64 -> Value
CqlTimeUuid :: !UUID -> Value
CqlMaybe :: (Maybe Value) -> Value
CqlList :: [Value] -> Value
CqlSet :: [Value] -> Value
CqlMap :: [(Value, Value)] -> Value

-- | binary protocol version &gt;= 3
CqlTuple :: [Value] -> Value

-- | binary protocol version &gt;= 3
CqlUdt :: [(Text, Value)] -> Value

-- | Tag some value with a phantom type.
newtype Tagged a b
Tagged :: b -> Tagged a b
[untag] :: Tagged a b -> b
retag :: Tagged a c -> Tagged b c
data R
data W
data S

-- | Protocol frame header.
data Header
Header :: !HeaderType -> !Version -> !Flags -> !StreamId -> !OpCode -> !Length -> Header
[headerType] :: Header -> !HeaderType
[version] :: Header -> !Version
[flags] :: Header -> !Flags
[streamId] :: Header -> !StreamId
[opCode] :: Header -> !OpCode
[bodyLength] :: Header -> !Length
data HeaderType

-- | A request frame header.
RqHeader :: HeaderType

-- | A response frame header.
RsHeader :: HeaderType

-- | Deserialise a frame header using the version specific decoding format.
header :: Version -> ByteString -> Either String Header

-- | The type denoting a protocol frame length.
newtype Length
Length :: Int32 -> Length
[lengthRepr] :: Length -> Int32

-- | Streams allow multiplexing of requests over a single communication
--   channel. The <a>StreamId</a> correlates <tt>Request</tt>s with
--   <tt>Response</tt>s.
data StreamId

-- | Create a StreamId from the given integral value. In version 2, a
--   StreamId is an <a>Int8</a> and in version 3 an <a>Int16</a>.
mkStreamId :: Integral i => i -> StreamId

-- | Convert the stream ID to an integer.
fromStreamId :: StreamId -> Int

-- | Type representing header flags. Flags form a monoid and can be used as
--   in <tt>compress &lt;&gt; tracing &lt;&gt; mempty</tt>.
data Flags

-- | Compression flag. If set, the frame body is compressed.
compress :: Flags

-- | Tracing flag. If a request support tracing and the tracing flag was
--   set, the response to this request will have the tracing flag set and
--   contain tracing information.
tracing :: Flags

-- | Check if a particular flag is present.
isSet :: Flags -> Flags -> Bool

-- | The type corresponding to the protocol request frame.
--   
--   The type parameter <tt>k</tt> denotes the kind of request. It is
--   present to allow distinguishing read operations from write operations.
--   Use <a>R</a> for read, <a>W</a> for write and <a>S</a> for schema
--   related operations.
--   
--   <tt>a</tt> represents the argument type and <tt>b</tt> the return type
--   of this request.
data Request k a b
RqStartup :: !Startup -> Request k a b
RqOptions :: !Options -> Request k a b
RqRegister :: !Register -> Request k a b
RqBatch :: !Batch -> Request k a b
RqAuthResp :: !AuthResponse -> Request k a b
RqPrepare :: !(Prepare k a b) -> Request k a b
RqQuery :: !(Query k a b) -> Request k a b
RqExecute :: !(Execute k a b) -> Request k a b

-- | Get the protocol <a>OpCode</a> corresponding to the given
--   <a>Request</a>.
getOpCode :: Request k a b -> OpCode

-- | Serialise the given request, optionally using compression. The result
--   is either an error description in case of failure or a binary protocol
--   frame, including <a>Header</a>, <a>Length</a> and body.
pack :: Tuple a => Version -> Compression -> Bool -> StreamId -> Request k a b -> Either String ByteString

-- | An options request, send prior to <a>Startup</a> to request the
--   server's startup options.
data Options
Options :: Options

-- | A startup request which is used when initialising a connection to the
--   server. It specifies the CQL version to use and optionally the
--   compression algorithm.
data Startup
Startup :: !CqlVersion -> !CompressionAlgorithm -> Startup

-- | A request send in response to a previous authentication challenge.
newtype AuthResponse
AuthResponse :: ByteString -> AuthResponse

-- | Register's the connection this request is made through, to receive
--   server events.
newtype Register
Register :: [EventType] -> Register

-- | Event types to register.
data EventType

-- | events related to change in the cluster topology
TopologyChangeEvent :: EventType

-- | events related to change of node status
StatusChangeEvent :: EventType

-- | events related to schema change
SchemaChangeEvent :: EventType

-- | A CQL query (select, insert, etc.).
data Query k a b
Query :: !(QueryString k a b) -> !(QueryParams a) -> Query k a b

-- | Query parameters.
data QueryParams a
QueryParams :: !Consistency -> !Bool -> a -> Maybe Int32 -> Maybe PagingState -> Maybe SerialConsistency -> QueryParams a

-- | consistency leven to use
[consistency] :: QueryParams a -> !Consistency

-- | skip metadata in response
[skipMetaData] :: QueryParams a -> !Bool

-- | query arguments
[values] :: QueryParams a -> a

-- | desired result set size
[pageSize] :: QueryParams a -> Maybe Int32
[queryPagingState] :: QueryParams a -> Maybe PagingState
[serialConsistency] :: QueryParams a -> Maybe SerialConsistency

-- | Consistency level for the serial phase of conditional updates.
data SerialConsistency
SerialConsistency :: SerialConsistency
LocalSerialConsistency :: SerialConsistency

-- | Allows executing a list of queries (prepared or not) as a batch.
data Batch
Batch :: !BatchType -> [BatchQuery] -> !Consistency -> Maybe SerialConsistency -> Batch
[batchType] :: Batch -> !BatchType
[batchQuery] :: Batch -> [BatchQuery]
[batchConsistency] :: Batch -> !Consistency
[batchSerialConsistency] :: Batch -> Maybe SerialConsistency

-- | A GADT to unify queries and prepared queries both of which can be used
--   in batch requests.
data BatchQuery
BatchQuery :: !(QueryString W a b) -> !a -> BatchQuery
BatchPrepared :: !(QueryId W a b) -> !a -> BatchQuery
data BatchType

-- | default, uses a batch log for atomic application
BatchLogged :: BatchType

-- | skip the batch log
BatchUnLogged :: BatchType

-- | used for batched counter updates
BatchCounter :: BatchType

-- | Prepare a query for later execution (cf. <a>Execute</a>).
newtype Prepare k a b
Prepare :: (QueryString k a b) -> Prepare k a b

-- | Executes a prepared query.
data Execute k a b
Execute :: !(QueryId k a b) -> !(QueryParams a) -> Execute k a b

-- | The type corresponding to the protocol response frame.
--   
--   The type parameter <tt>k</tt> denotes the kind of response. It is
--   present to allow distinguishing read operations from write operations.
--   Use <a>R</a> for read, <a>W</a> for write and <a>S</a> for schema
--   related operations.
--   
--   <tt>a</tt> represents the argument type and <tt>b</tt> the return type
--   of this response.
data Response k a b
RsError :: (Maybe UUID) -> !Error -> Response k a b
RsReady :: (Maybe UUID) -> !Ready -> Response k a b
RsAuthenticate :: (Maybe UUID) -> !Authenticate -> Response k a b
RsAuthChallenge :: (Maybe UUID) -> !AuthChallenge -> Response k a b
RsAuthSuccess :: (Maybe UUID) -> !AuthSuccess -> Response k a b
RsSupported :: (Maybe UUID) -> !Supported -> Response k a b
RsResult :: (Maybe UUID) -> !(Result k a b) -> Response k a b
RsEvent :: (Maybe UUID) -> !Event -> Response k a b

-- | Deserialise a <a>Response</a> from the given <a>ByteString</a>.
unpack :: (Tuple a, Tuple b) => Compression -> Header -> ByteString -> Either String (Response k a b)

-- | The server is ready to process queries. Response of a <tt>Startup</tt>
--   request.
data Ready
Ready :: Ready

-- | The server requires authentication.
newtype Authenticate
Authenticate :: Text -> Authenticate

-- | A server-send authentication challenge.
newtype AuthChallenge
AuthChallenge :: (Maybe ByteString) -> AuthChallenge

-- | Indicates the success of an authentication phase.
newtype AuthSuccess
AuthSuccess :: (Maybe ByteString) -> AuthSuccess

-- | Query response.
data Result k a b
VoidResult :: Result k a b
RowsResult :: !MetaData -> [b] -> Result k a b
SetKeyspaceResult :: !Keyspace -> Result k a b
PreparedResult :: !(QueryId k a b) -> !MetaData -> !MetaData -> Result k a b
SchemaChangeResult :: !SchemaChange -> Result k a b

-- | Part of a <tt>RowsResult</tt>. Describes the result set.
data MetaData
MetaData :: !Int32 -> Maybe PagingState -> [ColumnSpec] -> MetaData
[columnCount] :: MetaData -> !Int32
[pagingState] :: MetaData -> Maybe PagingState
[columnSpecs] :: MetaData -> [ColumnSpec]

-- | The column specification. Part of <a>MetaData</a> unless
--   <tt>skipMetaData</tt> in <tt>QueryParams</tt> was True.
data ColumnSpec
ColumnSpec :: !Keyspace -> !Table -> !Text -> !ColumnType -> ColumnSpec
[keyspace] :: ColumnSpec -> !Keyspace
[table] :: ColumnSpec -> !Table
[columnName] :: ColumnSpec -> !Text
[columnType] :: ColumnSpec -> !ColumnType

-- | The startup options supported by the server. Response of an
--   <tt>Options</tt> request.
data Supported
Supported :: [CompressionAlgorithm] -> [CqlVersion] -> Supported

-- | Messages send by the server without request, if the connection has
--   been <tt>Register</tt>ed to receive such events.
data Event
TopologyEvent :: !TopologyChange -> !SockAddr -> Event
StatusEvent :: !StatusChange -> !SockAddr -> Event
SchemaEvent :: !SchemaChange -> Event
data TopologyChange
NewNode :: TopologyChange
RemovedNode :: TopologyChange
data SchemaChange
SchemaCreated :: !Change -> SchemaChange
SchemaUpdated :: !Change -> SchemaChange
SchemaDropped :: !Change -> SchemaChange
data StatusChange
Up :: StatusChange
Down :: StatusChange
data Change
KeyspaceChange :: !Keyspace -> Change
TableChange :: !Keyspace -> !Table -> Change
TypeChange :: !Keyspace -> !Text -> Change

-- | Error response.
data Error
AlreadyExists :: !Text -> !Keyspace -> !Table -> Error
BadCredentials :: !Text -> Error
ConfigError :: !Text -> Error
Invalid :: !Text -> Error
IsBootstrapping :: !Text -> Error
Overloaded :: !Text -> Error
ProtocolError :: !Text -> Error
ServerError :: !Text -> Error
SyntaxError :: !Text -> Error
TruncateError :: !Text -> Error
Unauthorized :: !Text -> Error
Unprepared :: !Text -> !ByteString -> Error
Unavailable :: !Text -> !Consistency -> !Int32 -> !Int32 -> Error
[unavailMessage] :: Error -> !Text
[unavailConsistency] :: Error -> !Consistency
[unavailNumRequired] :: Error -> !Int32
[unavailNumAlive] :: Error -> !Int32
ReadTimeout :: !Text -> !Consistency -> !Int32 -> !Int32 -> !Bool -> Error
[rTimeoutMessage] :: Error -> !Text
[rTimeoutConsistency] :: Error -> !Consistency
[rTimeoutNumAck] :: Error -> !Int32
[rTimeoutNumRequired] :: Error -> !Int32
[rTimeoutDataPresent] :: Error -> !Bool
WriteTimeout :: !Text -> !Consistency -> !Int32 -> !Int32 -> !WriteType -> Error
[wTimeoutMessage] :: Error -> !Text
[wTimeoutConsistency] :: Error -> !Consistency
[wTimeoutNumAck] :: Error -> !Int32
[wTimeoutNumRequired] :: Error -> !Int32
[wTimeoutWriteType] :: Error -> !WriteType
data WriteType
WriteSimple :: WriteType
WriteBatch :: WriteType
WriteBatchLog :: WriteType
WriteUnloggedBatch :: WriteType
WriteCounter :: WriteType
class PrivateTuple a => Tuple a
count :: PrivateTuple a => Tagged a Int
check :: PrivateTuple a => Tagged a ([ColumnType] -> [ColumnType])
tuple :: PrivateTuple a => Version -> [ColumnType] -> Get a
store :: PrivateTuple a => Version -> Putter a

-- | A row is a vector of <a>Value</a>s.
data Row
mkRow :: [(Value, ColumnType)] -> Row

-- | Convert a row element.
fromRow :: Cql a => Int -> Row -> Either String a
columnTypes :: Row -> [ColumnType]
rowLength :: Row -> Int

-- | Record/Tuple conversion. For example:
--   
--   <pre>
--   data Peer = Peer
--       { peerAddr :: IP
--       , peerRPC  :: IP
--       , peerDC   :: Text
--       , peerRack :: Text
--       } deriving Show
--   
--   recordInstance ''Peer
--   
--   map asRecord &lt;$&gt; performQuery "SELECT peer, rpc_address, data_center, rack FROM system.peers"
--   </pre>
--   
--   The generated type-class instance maps between record and tuple
--   constructors:
--   
--   <pre>
--   type instance TupleType Peer = (IP, IP, Text, Text)
--   
--   instance Record Peer where
--       asTuple (Peer a b c d) = (a, b, c, d)
--       asRecord (a, b, c, d)  = Peer a b c d
--   </pre>
class Record a
asTuple :: Record a => a -> TupleType a
asRecord :: Record a => TupleType a -> a
recordInstance :: Name -> Q [Dec]