GetShardIterator.hs

{-# LANGUAGE DataKinds                   #-}
{-# LANGUAGE DeriveGeneric               #-}
{-# LANGUAGE FlexibleInstances           #-}
{-# LANGUAGE GeneralizedNewtypeDeriving  #-}
{-# LANGUAGE LambdaCase                  #-}
{-# LANGUAGE NoImplicitPrelude           #-}
{-# LANGUAGE OverloadedStrings           #-}
{-# LANGUAGE RecordWildCards             #-}
{-# LANGUAGE TypeFamilies                #-}

{-# OPTIONS_GHC -fno-warn-unused-imports #-}

-- Module      : Network.AWS.Kinesis.GetShardIterator
-- Copyright   : (c) 2013-2014 Brendan Hay <brendan.g.hay@gmail.com>
-- License     : This Source Code Form is subject to the terms of
--               the Mozilla Public License, v. 2.0.
--               A copy of the MPL can be found in the LICENSE file or
--               you can obtain it at http://mozilla.org/MPL/2.0/.
-- Maintainer  : Brendan Hay <brendan.g.hay@gmail.com>
-- Stability   : experimental
-- Portability : non-portable (GHC extensions)

-- | Gets a shard iterator. A shard iterator expires five minutes after it is
-- returned to the requester. A shard iterator specifies the position in the
-- shard from which to start reading data records sequentially. A shard
-- iterator specifies this position using the sequence number of a data record
-- in a shard. A sequence number is the identifier associated with every
-- record ingested in the Amazon Kinesis stream. The sequence number is
-- assigned when a record is put into the stream. You must specify the shard
-- iterator type. For example, you can set the ShardIteratorType parameter to
-- read exactly from the position denoted by a specific sequence number by
-- using the AT_SEQUENCE_NUMBER shard iterator type, or right after the
-- sequence number by using the AFTER_SEQUENCE_NUMBER shard iterator type,
-- using sequence numbers returned by earlier calls to PutRecord, GetRecords,
-- or DescribeStream. You can specify the shard iterator type TRIM_HORIZON in
-- the request to cause ShardIterator to point to the last untrimmed record in
-- the shard in the system, which is the oldest data record in the shard. Or
-- you can point to just after the most recent record in the shard, by using
-- the shard iterator type LATEST, so that you always read the most recent
-- data in the shard. When you repeatedly read from an Amazon Kinesis stream
-- use a GetShardIterator request to get the first shard iterator to to use in
-- your first GetRecords request and then use the shard iterator returned by
-- the GetRecords request in NextShardIterator for subsequent reads. A new
-- shard iterator is returned by every GetRecords request in
-- NextShardIterator, which you use in the ShardIterator parameter of the next
-- GetRecords request. If a GetShardIterator request is made too often, you
-- receive a ProvisionedThroughputExceededException. For more information
-- about throughput limits, see GetRecords. If the shard is closed, the
-- iterator can't return more data, and GetShardIterator returns null for its
-- ShardIterator. A shard can be closed using SplitShard or MergeShards.
-- GetShardIterator has a limit of 5 transactions per second per account per
-- open shard.
--
-- <http://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetShardIterator.html>
module Network.AWS.Kinesis.GetShardIterator
    (
    -- * Request
      GetShardIterator
    -- ** Request constructor
    , getShardIterator
    -- ** Request lenses
    , gsiShardId
    , gsiShardIteratorType
    , gsiStartingSequenceNumber
    , gsiStreamName

    -- * Response
    , GetShardIteratorResponse
    -- ** Response constructor
    , getShardIteratorResponse
    -- ** Response lenses
    , gsirShardIterator
    ) where

import Network.AWS.Prelude
import Network.AWS.Request.JSON
import Network.AWS.Kinesis.Types
import qualified GHC.Exts

data GetShardIterator = GetShardIterator
    { _gsiShardId                :: Text
    , _gsiShardIteratorType      :: Text
    , _gsiStartingSequenceNumber :: Maybe Text
    , _gsiStreamName             :: Text
    } deriving (Eq, Ord, Show)

-- | 'GetShardIterator' constructor.
--
-- The fields accessible through corresponding lenses are:
--
-- * 'gsiShardId' @::@ 'Text'
--
-- * 'gsiShardIteratorType' @::@ 'Text'
--
-- * 'gsiStartingSequenceNumber' @::@ 'Maybe' 'Text'
--
-- * 'gsiStreamName' @::@ 'Text'
--
getShardIterator :: Text -- ^ 'gsiStreamName'
                 -> Text -- ^ 'gsiShardId'
                 -> Text -- ^ 'gsiShardIteratorType'
                 -> GetShardIterator
getShardIterator p1 p2 p3 = GetShardIterator
    { _gsiStreamName             = p1
    , _gsiShardId                = p2
    , _gsiShardIteratorType      = p3
    , _gsiStartingSequenceNumber = Nothing
    }

-- | The shard ID of the shard to get the iterator for.
gsiShardId :: Lens' GetShardIterator Text
gsiShardId = lens _gsiShardId (\s a -> s { _gsiShardId = a })

-- | Determines how the shard iterator is used to start reading data records
-- from the shard. The following are the valid shard iterator types:
-- AT_SEQUENCE_NUMBER - Start reading exactly from the position denoted by a
-- specific sequence number. AFTER_SEQUENCE_NUMBER - Start reading right
-- after the position denoted by a specific sequence number. TRIM_HORIZON -
-- Start reading at the last untrimmed record in the shard in the system,
-- which is the oldest data record in the shard. LATEST - Start reading just
-- after the most recent record in the shard, so that you always read the
-- most recent data in the shard.
gsiShardIteratorType :: Lens' GetShardIterator Text
gsiShardIteratorType =
    lens _gsiShardIteratorType (\s a -> s { _gsiShardIteratorType = a })

-- | The sequence number of the data record in the shard from which to start
-- reading from.
gsiStartingSequenceNumber :: Lens' GetShardIterator (Maybe Text)
gsiStartingSequenceNumber =
    lens _gsiStartingSequenceNumber
        (\s a -> s { _gsiStartingSequenceNumber = a })

-- | The name of the stream.
gsiStreamName :: Lens' GetShardIterator Text
gsiStreamName = lens _gsiStreamName (\s a -> s { _gsiStreamName = a })

newtype GetShardIteratorResponse = GetShardIteratorResponse
    { _gsirShardIterator :: Maybe Text
    } deriving (Eq, Ord, Show, Monoid)

-- | 'GetShardIteratorResponse' constructor.
--
-- The fields accessible through corresponding lenses are:
--
-- * 'gsirShardIterator' @::@ 'Maybe' 'Text'
--
getShardIteratorResponse :: GetShardIteratorResponse
getShardIteratorResponse = GetShardIteratorResponse
    { _gsirShardIterator = Nothing
    }

-- | The position in the shard from which to start reading data records
-- sequentially. A shard iterator specifies this position using the sequence
-- number of a data record in a shard.
gsirShardIterator :: Lens' GetShardIteratorResponse (Maybe Text)
gsirShardIterator =
    lens _gsirShardIterator (\s a -> s { _gsirShardIterator = a })

instance ToPath GetShardIterator where
    toPath = const "/"

instance ToQuery GetShardIterator where
    toQuery = const mempty

instance ToHeaders GetShardIterator

instance ToJSON GetShardIterator where
    toJSON GetShardIterator{..} = object
        [ "StreamName"             .= _gsiStreamName
        , "ShardId"                .= _gsiShardId
        , "ShardIteratorType"      .= _gsiShardIteratorType
        , "StartingSequenceNumber" .= _gsiStartingSequenceNumber
        ]

instance AWSRequest GetShardIterator where
    type Sv GetShardIterator = Kinesis
    type Rs GetShardIterator = GetShardIteratorResponse

    request  = post "GetShardIterator"
    response = jsonResponse

instance FromJSON GetShardIteratorResponse where
    parseJSON = withObject "GetShardIteratorResponse" $ \o -> GetShardIteratorResponse
        <$> o .:? "ShardIterator"