Network.EtcdV3

Simple lib to access Etcd over gRPC.

This library offers a low-on-details EtcdV3 APIs to easily add distributed system mechanisms into your Haskell applications.

This library uses the Helpers module from 'http2-client-grpc', which may trade some functionalities for the sake of simplicity. A typically hidden functionality is the possibility to abort a query upon a client decision (e.g., while waiting for some Lock).

In general, this library provides some simplification to express the input messages of RPCs. For instance, the MVCC capabilities are mostly hidden from the _querying_ side of this library (i.e., queries will requet the latest revision of a key/value pair). It is pretty simple, however, to reuse the smart constructor (such as putReq and continue editing values with lens) and then call the gRPC RPC in a one liner.

A reason for this design is that the intended user of this library will run a continuous loop to acquire some leadership or monitor some values for the whole duration of a program.

Generalities.

etcdClientConfigSimple :: HostName -> PortNumber -> UseTlsOrNot -> GrpcClientConfig

EtcdClient configuration.

type EtcdQuery a = IO (Maybe a)

Type alias to simplify type signatures.

Reading.

data KeyRange

Data type to unify the three addressing schemes in etcd.

See range.

Constructors

SingleKey !ByteString

Exactly one key.

FromKey !ByteString

Prefixed !ByteString

Instances

Eq KeyRange

Defined in Network.EtcdV3

Methods

(==) :: KeyRange -> KeyRange -> Bool

(/=) :: KeyRange -> KeyRange -> Bool

Ord KeyRange

Defined in Network.EtcdV3

Methods

compare :: KeyRange -> KeyRange -> Ordering

(<) :: KeyRange -> KeyRange -> Bool

(<=) :: KeyRange -> KeyRange -> Bool

(>) :: KeyRange -> KeyRange -> Bool

(>=) :: KeyRange -> KeyRange -> Bool

max :: KeyRange -> KeyRange -> KeyRange

min :: KeyRange -> KeyRange -> KeyRange

Show KeyRange

Defined in Network.EtcdV3

Methods

showsPrec :: Int -> KeyRange -> ShowS

show :: KeyRange -> String

showList :: [KeyRange] -> ShowS

range

Arguments

:: GrpcClient

Initialized gRPC client.

-> KeyRange

Looked-up range.

-> EtcdQuery RangeResponse

Lookup a range of values

rangeReq :: KeyRange -> RangeRequest

rangeResponsePairs :: Getting (Endo [(ByteString, ByteString)]) RangeResponse (ByteString, ByteString)

Specific fold to get the key-values of a RangeResponse

Typical usage is:

x <- range grpc (Prefixed "some-dir") print $ x ^.. _Just . rangePairs

Note that Etcd RangeResponse is a rich object, please refer to Etcd documentation to understand what you will miss out (e.g., whether the list is complete or not).

Granting leases.

grantLease

Arguments

:: GrpcClient

Initialized gRPC client.

-> Int64

TTL for the lease.

-> EtcdQuery LeaseGrantResponse

Asks for a lease of a given duration.

data GrantedLease

Opaque lease result.

Show instance used for printing purposes only.

Instances

Show GrantedLease

Defined in Network.EtcdV3

Methods

showsPrec :: Int -> GrantedLease -> ShowS

show :: GrantedLease -> String

showList :: [GrantedLease] -> ShowS

fromLeaseGrantResponse :: LeaseGrantResponse -> GrantedLease

Constructor for GrantedLease.

keepAlive

Arguments

:: GrpcClient

Initialized gRPC client.

-> GrantedLease

A previously-granted lease.

-> EtcdQuery LeaseKeepAliveResponse

Keep a lease alive.

Writing.

put

Arguments

:: GrpcClient

initialized gRPC client

-> ByteString

Key.

-> ByteString

Value.

-> Maybe GrantedLease

Lease on the key.

-> EtcdQuery PutResponse

Put one value.

putReq :: ByteString -> ByteString -> Maybe GrantedLease -> PutRequest

delete

Arguments

:: GrpcClient

Initialized gRPC client.

-> KeyRange

Deleted range.

-> EtcdQuery DeleteRangeResponse

Delete a range of values.

delReq :: KeyRange -> DeleteRangeRequest

Locking.

data AcquiredLock

Opaque lock.

Show instance used for printing purposes only.

Instances

Show AcquiredLock

Defined in Network.EtcdV3

Methods

showsPrec :: Int -> AcquiredLock -> ShowS

show :: AcquiredLock -> String

showList :: [AcquiredLock] -> ShowS

fromLockResponse :: LockResponse -> AcquiredLock

lock

Arguments

:: GrpcClient

Initialized gRPC client.

-> ByteString

Lock Name

-> GrantedLease

Previously-granted lease that will bound the lifetime of the lock ownership.

-> EtcdQuery LockResponse

unlock

Arguments

:: GrpcClient

Initialized gRPC client.

-> AcquiredLock

Previously-acquired lock.

-> EtcdQuery UnlockResponse

Transactions.

transaction

Arguments

:: GrpcClient

Initialized gRPC client.

-> TxnRequest

Transaction

-> EtcdQuery TxnResponse

Issue a transaction request, performing many modifications at once.

See successTxnReq for a smart constructor of transaction request.

A Few Smart Constructors To Make Life Easy When Building Transactions.

successTxnReq :: [Compare] -> [PutRequest] -> [DeleteRangeRequest] -> [RangeRequest] -> TxnRequest

Smart constructor, to use in conjunction with other smart constructor which give a small DSL for the common cases. The proto-lens generated code is fine but requires qualified imports to avoid namespace clashes.

Example use: putStrLn $ Data.ProtoLens.showMessage$ successTxnReq [kvEq "hello" "world"] [putReq "txn-written" "1234" Nothing] [] [] compare { target: VALUE key: "hello" value: "world" } success { request_put { key: "txn-written" value: "1234" } }

kvEq :: ByteString -> ByteString -> Compare

kvNeq :: ByteString -> ByteString -> Compare

kvGt :: ByteString -> ByteString -> Compare

kvLt :: ByteString -> ByteString -> Compare

Watches.

watchForever

Arguments

:: GrpcClient

Initialized gRPC client.

-> [WatchRequest]

List of watches to register.

-> (a -> WatchResponse -> IO a)

State-passing handler for handling watches.

-> a

Initial state.

-> IO (Either TooMuchConcurrency ())

Starts some watches until an exception occurs.

Alas there is no simple way to discard a watch or stop a stream with this method as http2-client-grpc does not yet expose an OutgoingEvent to forcefully close the client stream.

See watchReq for building watch requests.

watchReq :: KeyRange -> [WatchCreateRequest'FilterType] -> Int64 -> WatchRequest

Leader election.

newtype Election

A newtype around ByteString to speak about election names.

Constructors

Election

Fields

• _getElectionName :: ByteString

Instances

Eq Election

Defined in Network.EtcdV3

Methods

(==) :: Election -> Election -> Bool

(/=) :: Election -> Election -> Bool

Ord Election

Defined in Network.EtcdV3

Methods

compare :: Election -> Election -> Ordering

(<) :: Election -> Election -> Bool

(<=) :: Election -> Election -> Bool

(>) :: Election -> Election -> Bool

(>=) :: Election -> Election -> Bool

max :: Election -> Election -> Election

min :: Election -> Election -> Election

Show Election

Defined in Network.EtcdV3

Methods

showsPrec :: Int -> Election -> ShowS

show :: Election -> String

showList :: [Election] -> ShowS

IsString Election

Defined in Network.EtcdV3

Methods

fromString :: String -> Election

data LeaderEvidence

An Opaque type around returned leader key.

runForLeadership

Arguments

:: GrpcClient

Initialized gRPC client.

-> Election

An election to run for.

-> GrantedLease

A lease delimiting the leadership duration.

-> ByteString

The initially-proclaimed value.

-> EtcdQuery CampaignResponse

Waits until elected.

fromCampaignResponse :: CampaignResponse -> Maybe LeaderEvidence

Helper to retrieve an evidence that we are a leader from a CampaignResponse.

proclaim

Arguments

:: GrpcClient

Initialized gRPC client.

-> LeaderEvidence

Proof of recent successful participation to a leader-election.

-> ByteString

New value to proclaim.

-> EtcdQuery ProclaimResponse

As a leader, proclaim a new value.

Observers will be notified.

resign

Arguments

:: GrpcClient

Initialized gRPC client.

-> LeaderEvidence

Proof of recent successful participation to a leader-election.

-> EtcdQuery ResignResponse

Resign from leadership.

If other campaigners are waiting for the role, they will get elected.

getProclaimedValue

Arguments

:: GrpcClient

Initialized gRPC client.

-> Election

Election to read value from.

-> EtcdQuery LeaderResponse

As a bystander of an election, get the proclaimed value.

observeProclaimedValues

Arguments

:: GrpcClient

Initialized gRPC client.

-> Election

Election to wait for values from.

-> (a -> LeaderResponse -> IO a)

State-passing handler for handling iteratively updated proclaimed values.

-> a

An initial state.

-> IO (Either TooMuchConcurrency a)

As a bystander of an election, get notified for every proclaimed value.

proclaimReq :: LeaderEvidence -> ByteString -> ProclaimRequest

campaignReq :: Election -> GrantedLease -> ByteString -> CampaignRequest

resignReq :: LeaderEvidence -> ResignRequest

leaderReq :: Election -> LeaderRequest

re-exports

defMessage :: Message msg => msg

A message with all fields set to their default values.

Satisfies encodeMessage defMessage == "" and decodeMessage "" == Right defMessage.

module Control.Lens