Your opinion will help to improve our service
Leave a feedback >Make sure that you can compile and run core tests and read a basic example Writing your first HTTP server.
Microservices that have state often work with database to store their data and replicate that state across instances of the microservice. In this tutorial we will write a service that is a simple key-value storage on top of Redis database. The service would have the following Rest API:
/v1/key-value
with query parameters key
and value
stores the provided key and value or 409 Conflict
if such key already exists/v1/key-value
with query parameter key
returns the value if it exists or 404 Not Found
if it is missing/v1/key-value
with query parameter key
deletes the key if it exists and returns number of deleted keys (cannot be more than 1, since keys are unique in Redis database)Like in Writing your first HTTP server we create a component for handling HTTP requests:
Note that the component holds a storages::redis::ClientPtr - a client to the Redis database. That client is thread safe, you can use it concurrently from different threads and tasks.
To access the database from our new component we need to find the Redis component and request a client to a specific cluster by its name. After that we are ready to make requests.
In this sample we use a single handler to deal with all the HTTP methods. The KeyValue::HandleRequestThrow member function mostly dispatches the request to one of the member functions that actually implement the key-value storage logic:
Handle*
functions are invoked concurrently on the same instance of the handler class. In this sample the KeyValue component only uses the thread safe DB client. In more complex cases synchronization primitives should be used or data must not be mutated.Executing a query to the Redis database is as simple as calling the corresponding method of storages::redis::ClientPtr.
Note that some methods return an optional result, which must be checked. Here it can indicate a missing key value.
Here we use storages::redis::Client::SetIfNotExist() to ensure not to change already existing keys.
Note that mutating queries are automatically executed on a master instance.
Static configuration of service is quite close to the configuration from Writing your first HTTP server except for the handler and DB:
components_manager:
components: # Configuring components that were registered via component_list
handler-key-value:
path: /v1/key-value # Registering handler by URL '/v1/key-value'.
method: GET,POST,DELETE # GET, POST and DELETE requests only.
task_processor: main-task-processor # Run it on CPU bound task processor
handler-script:
path: /v1/script # Registering handler by URL '/v1/key-value'.
method: POST # GET, POST and DELETE requests only.
task_processor: main-task-processor # Run it on CPU bound task processor
key-value-database:
groups:
- config_name: taxi-tmp # Key to lookup in secdist configuration
db: taxi-tmp # Name to refer to the cluster in components::Redis::GetClient()
subscribe_groups: # Array of redis clusters to work with in subscribe mode
thread_pools:
redis_thread_pool_size: 8
sentinel_thread_pool_size: 1
testsuite-support:
server:
# ...
components::Redis takes database connection information from components::DefaultSecdistProvider, so it should be also configured:
default-secdist-provider: # Component that loads configuration of hosts and passwords
config: /etc/redis_service/secure_data.json # Values are supposed to be stored in this file
missing-ok: true # ... but if the file is missing it is still ok
environment-secrets-key: SECDIST_CONFIG # ... values will be loaded from this environment value
The actual content of secure_data.json
or SECDIST_CONFIG
is described at components::Redis.
Finally, after writing down the dynamic config values into file at dynamic-config-fallbacks.fallback-path
, we add our component to the components::MinimalServerComponentList(), and start the server with static config kStaticConfig
.
To build the sample, execute the following build steps at the userver root directory:
The sample could be started by running make start-userver-samples-redis_service
. The command would invoke testsuite start target that sets proper paths in the configuration files, prepares and starts the DB, and starts the service.
To start the service manually start the DB server and run ./samples/redis_service/userver-samples-redis_service -c </path/to/static_config.yaml>
.
Now you can send a request to your service from another terminal:
$ curl -X POST 'localhost:8088/v1/key-value?key=hello&value=world' -i
HTTP/1.1 201 Created
Date: Wed, 27 Oct 2021 16:45:13 UTC
Content-Type: text/html
X-YaSpanId: 015fb0becd2926ef
X-YaRequestId: 7830671d7dd2462ba9043db532c2b82a
Server: userver/2.0 (20211027123413; rv:c1879aa03)
X-YaTraceId: d7422d7bcdc9493997fc687f8be24883
Connection: keep-alive
Content-Length: 5
world
$ curl -X DELETE 'localhost:8088/v1/key-value?key=hello&value=world' -i
HTTP/1.1 200 OK
Date: Wed, 27 Oct 2021 16:46:35 UTC
Content-Type: text/html
X-YaSpanId: e83698e2ef8cc729
X-YaRequestId: ffbaacae38e64bb588affa10b928b759
Server: userver/2.0 (20211027123413; rv:c1879aa03)
X-YaTraceId: cd3e6acc299742739bb22c795b6ef3a7
Connection: keep-alive
Content-Length: 1
1
Unit tests for the service could be implemented with one of UTEST macros in the following way:
Functional tests for the service could be implemented using the testsuite. To do that you have to:
Add the Redis Secdist settings info to the service environment variable:
The auto_client_deps fixture already knows about the redis_store fixture, so there's no need to override the extra_client_deps fixture.
For details on Redis Secdist format, see components::Redis.
See the full example: