grpc-etcd-client-0.1.2.0: gRPC client for etcd

Safe HaskellNone
LanguageHaskell2010

Network.EtcdV3

Contents

Description

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.

Synopsis

Generalities.

type EtcdQuery a = IO (Maybe a) Source #

Type alias to simplify type signatures.

Reading.

data KeyRange Source #

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 Source # 
Instance details

Defined in Network.EtcdV3

Ord KeyRange Source # 
Instance details

Defined in Network.EtcdV3

Show KeyRange Source # 
Instance details

Defined in Network.EtcdV3

range Source #

Arguments

:: GrpcClient

Initialized gRPC client.

-> KeyRange

Looked-up range.

-> EtcdQuery RangeResponse 

Lookup a range of values

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

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 Source #

Arguments

:: GrpcClient

Initialized gRPC client.

-> Int64

TTL for the lease.

-> EtcdQuery LeaseGrantResponse 

Asks for a lease of a given duration.

data GrantedLease Source #

Opaque lease result.

Show instance used for printing purposes only.

Instances
Show GrantedLease Source # 
Instance details

Defined in Network.EtcdV3

keepAlive Source #

Arguments

:: GrpcClient

Initialized gRPC client.

-> GrantedLease

A previously-granted lease.

-> EtcdQuery LeaseKeepAliveResponse 

Keep a lease alive.

Writing.

put Source #

Arguments

:: GrpcClient

initialized gRPC client

-> ByteString

Key.

-> ByteString

Value.

-> Maybe GrantedLease

Lease on the key.

-> EtcdQuery PutResponse 

Put one value.

delete Source #

Arguments

:: GrpcClient

Initialized gRPC client.

-> KeyRange

Deleted range.

-> EtcdQuery DeleteRangeResponse 

Delete a range of values.

Locking.

data AcquiredLock Source #

Opaque lock.

Show instance used for printing purposes only.

Instances
Show AcquiredLock Source # 
Instance details

Defined in Network.EtcdV3

lock Source #

Arguments

:: GrpcClient

Initialized gRPC client.

-> ByteString

Lock Name

-> GrantedLease

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

-> EtcdQuery LockResponse 

unlock Source #

Arguments

:: GrpcClient

Initialized gRPC client.

-> AcquiredLock

Previously-acquired lock.

-> EtcdQuery UnlockResponse 

Transactions.

transaction Source #

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 Source #

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" } }

Watches.

watchForever Source #

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.

Leader election.

newtype Election Source #

A newtype around ByteString to speak about election names.

Constructors

Election 
Instances
Eq Election Source # 
Instance details

Defined in Network.EtcdV3

Ord Election Source # 
Instance details

Defined in Network.EtcdV3

Show Election Source # 
Instance details

Defined in Network.EtcdV3

IsString Election Source # 
Instance details

Defined in Network.EtcdV3

data LeaderEvidence Source #

An Opaque type around returned leader key.

runForLeadership Source #

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 Source #

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

proclaim Source #

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 Source #

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 Source #

Arguments

:: GrpcClient

Initialized gRPC client.

-> Election

Election to read value from.

-> EtcdQuery LeaderResponse 

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

observeProclaimedValues Source #

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.

re-exports

defMessage :: Message msg => msg #

A message with all fields set to their default values.

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