riak_dart 0.4.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 27

riak_dart #

An unofficial Riak client for dart based on Riaks ProtoBuf API.

riak_dart and generated_protobuf library #

This package consists of the riak_dart library and the generated_protobuf library.

The riak_dart libary contains the RiakClient, which provides a request method for each defined Riak ProtoBuf API request. Since large parts of the method documentation of RiakClient are just copied from the Riak ProtoBuf API, the documentation of this class does not respect the dart documentation guidelines; also grammer and spelling is sometimes inconsistent, camel case (dart) is mixed with snake case (protobuf), and dead/outdatet links can occur.

The generated_protobuf library on the other hand contains the files generated from Riaks ProtoBuf sourcefiles. The generated classes where not altered, what also means that they are not documented! Rather methods in the riak_dart library using or returning classes from generated_protobuf explain their usage. You can always take a look at the official Riak ProtoBuf Api documantation, especially for more information about the messages.

Example #

import 'package:riak_dart/riak_dart.dart';
import 'package:riak_dart/generated_protobuf.dart' hide MapEntry;
import 'dart:convert';

Future<void> main() async {
  // Initiate a connection
  RiakClient client = await RiakClient.connect(host: '192.168.178.145');
  // Set the error callback
  client.onError = print;

  // Choose a bucket to use
  List<int> bucket = utf8.encode('default');
  // Create a key
  List<int> key = utf8.encode('Hello');
  // Create some content
  RpbContent content = new RpbContent();
  content.value = utf8.encode('World');
  // Store the content
  await client.storeObject(bucket: bucket, key: key, content: content);

  // Fetch content
  RpbGetResp response = await client.fetchObject(bucket: bucket, key: key);
  if (response.content.isNotEmpty) {
    print(utf8.decode(response.content.first.value));
  } else {
    print('Nothing found using this key!');
  }

  // Close the client
  await client.closeGracefully();
}

Useful Notes #

Error handling #

Errors and exceptions can occure in two ways:

  1. A call to a request method of the RiakClient returns a future or a stream which may complete with / contain the following errors and exceptions:
    • A request answered with a response code other than registered in the expectedResponseTypes top-level constant will result in a WrongResponseCodeException
    • A Riak side error will result in a RpbErrorRespException
  2. There are some exceptions that do not belong to a request. They are forwarded to the onError callback of the RiakClient:
    • If a socket error (e.g. connection releated) happens, the error is passed to this callback
    • If an empty message without content or message code is received, this callback is invoked with an EmptyMessageException
    • If a message with an unknown message code is received, this callback is invoked with an UnknownMessageCodeException
    • If a message is received while there is no pending request, this callback is invoked with an UnexpectedMessageException

Experimental TLS/SSL #

Documentation on how to initiate a TLS encrypted connection with Riak is very sparse. The startTls method of RiakClient should therefor be considered experimental. Any kind of feedback, whether it works or breaks things, is very welcomed!

The MapEntry Problem #

The generate_protobuf library was generated from an unaltered version Riaks ProtoBuf source files. One of the messages defined there is MapEntry, what leads to a name collision with the build-in class MapEntry from dart:core. If you need darts MapEntry class explicitly in a file that imports from generated_protobuf consider

import 'package:riak_dart/generated_protobuf.dart' hide MapEntry;

if you don't need the generated MapEntry class, or

import 'package:riak_dart/generated_protobuf.dart' hide MapEntry;
import 'package:riak_dart/generated_protobuf.dart' as proto show MapEntry;

if you need it and refer to it as proto.MapEntry.

Performance optimization by Parallelism #

Most methods return a future with a response object matching the request, some streaming methodes use a stream of response objects to represent the method result. Sometimes, not awaiting a future, but executing multiple requests and awaiting a collecion of futures, can increase performance signicifantly. For example, to store multiple objects, consider this:

Future storeMultiple(RiakClient client, Map<String, String> keyValueMap) {
  List<int> bucket = utf8.encode('default');
  Iterable<Future> storeFutures = keyValueMap.keys.map<Future>(
      (String key) => client.storeObject(
          bucket: bucket,
          key: utf8.encode(key),
          content: new RpbContent()..value = utf8.encode(keyValueMap[key])));
  return Future.wait(storeFutures);
}

The more elements the keyValueMap contains, the faster this code will run compared to awaiting every storing response in sequence due to optimizations on network level.

[0.4.0] - 07.10.2019

  • Initial release to pub

example/example.dart

import 'package:riak_dart/riak_dart.dart';
import 'package:riak_dart/generated_protobuf.dart' hide MapEntry;
import 'dart:convert';

Future<void> main() async {
  // Initiate a connection
  RiakClient client = await RiakClient.connect(host: '192.168.178.145');
  // Set the error callback
  client.onError = print;

  // Choose a bucket to use
  List<int> bucket = utf8.encode('default');
  // Create a key
  List<int> key = utf8.encode('Hello');
  // Create some content
  RpbContent content = new RpbContent();
  content.value = utf8.encode('World');
  // Store the content
  await client.storeObject(bucket: bucket, key: key, content: content);

  // Fetch content
  RpbGetResp response = await client.fetchObject(bucket: bucket, key: key);
  if (response.content.isNotEmpty) {
    print(utf8.decode(response.content.first.value));
  } else {
    print('Nothing found using this key!');
  }

  // Close the client
  await client.closeGracefully();
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  riak_dart: ^0.4.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:riak_dart/riak_dart.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
11
Health:
Code health derived from static analysis. [more]
5
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
27
Learn more about scoring.

We analyzed this package on Dec 6, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.6.1
  • pana: 0.12.21

Health suggestions

Fix lib/src/generated_protobuf/riak_kv.pbjson.dart. (-66.30 points)

Analysis of lib/src/generated_protobuf/riak_kv.pbjson.dart reported 217 hints, including:

line 8 col 33: Avoid const keyword.

line 10 col 8: Avoid const keyword.

line 11 col 5: Avoid const keyword.

line 15 col 32: Avoid const keyword.

line 17 col 8: Avoid const keyword.

Fix lib/src/generated_protobuf/riak_dt.pbjson.dart. (-43.53 points)

Analysis of lib/src/generated_protobuf/riak_dt.pbjson.dart reported 114 hints, including:

line 8 col 23: Avoid const keyword.

line 10 col 8: Avoid const keyword.

line 11 col 5: Avoid const keyword.

line 12 col 5: Avoid const keyword.

line 14 col 8: Avoid const keyword.

Fix lib/src/generated_protobuf/riak_ts.pbjson.dart. (-35.99 points)

Analysis of lib/src/generated_protobuf/riak_ts.pbjson.dart reported 89 hints, including:

line 8 col 27: Avoid const keyword.

line 10 col 8: Avoid const keyword.

line 11 col 5: Avoid const keyword.

line 12 col 5: Avoid const keyword.

line 13 col 5: Avoid const keyword.

Fix additional 28 files with analysis or formatting issues. (-81.08 points)

Additional issues in the following files:

  • lib/src/generated_protobuf/riak.pbjson.dart (86 hints)
  • lib/src/generated_protobuf/riak_yokozuna.pbjson.dart (31 hints)
  • lib/src/riak_client.dart (22 hints)
  • lib/src/generated_protobuf/riak_search.pbjson.dart (20 hints)
  • lib/src/abstract_client.dart (16 hints)
  • lib/src/stream_utils/length_based_stream_transformer.dart (4 hints)
  • lib/src/stream_utils/length_prepender_sink.dart (3 hints)
  • lib/src/messages.dart (1 hint)
  • lib/generated_protobuf.dart (Run dartfmt to format lib/generated_protobuf.dart.)
  • lib/riak_dart.dart (Run dartfmt to format lib/riak_dart.dart.)
  • lib/src/generated_protobuf/riak.pb.dart (Run dartfmt to format lib/src/generated_protobuf/riak.pb.dart.)
  • lib/src/generated_protobuf/riak.pbenum.dart (Run dartfmt to format lib/src/generated_protobuf/riak.pbenum.dart.)
  • lib/src/generated_protobuf/riak.pbserver.dart (Run dartfmt to format lib/src/generated_protobuf/riak.pbserver.dart.)
  • lib/src/generated_protobuf/riak_dt.pb.dart (Run dartfmt to format lib/src/generated_protobuf/riak_dt.pb.dart.)
  • lib/src/generated_protobuf/riak_dt.pbenum.dart (Run dartfmt to format lib/src/generated_protobuf/riak_dt.pbenum.dart.)
  • lib/src/generated_protobuf/riak_dt.pbserver.dart (Run dartfmt to format lib/src/generated_protobuf/riak_dt.pbserver.dart.)
  • lib/src/generated_protobuf/riak_kv.pb.dart (Run dartfmt to format lib/src/generated_protobuf/riak_kv.pb.dart.)
  • lib/src/generated_protobuf/riak_kv.pbenum.dart (Run dartfmt to format lib/src/generated_protobuf/riak_kv.pbenum.dart.)
  • lib/src/generated_protobuf/riak_kv.pbserver.dart (Run dartfmt to format lib/src/generated_protobuf/riak_kv.pbserver.dart.)
  • lib/src/generated_protobuf/riak_search.pb.dart (Run dartfmt to format lib/src/generated_protobuf/riak_search.pb.dart.)
  • lib/src/generated_protobuf/riak_search.pbenum.dart (Run dartfmt to format lib/src/generated_protobuf/riak_search.pbenum.dart.)
  • lib/src/generated_protobuf/riak_search.pbserver.dart (Run dartfmt to format lib/src/generated_protobuf/riak_search.pbserver.dart.)
  • lib/src/generated_protobuf/riak_ts.pb.dart (Run dartfmt to format lib/src/generated_protobuf/riak_ts.pb.dart.)
  • lib/src/generated_protobuf/riak_ts.pbenum.dart (Run dartfmt to format lib/src/generated_protobuf/riak_ts.pbenum.dart.)
  • lib/src/generated_protobuf/riak_ts.pbserver.dart (Run dartfmt to format lib/src/generated_protobuf/riak_ts.pbserver.dart.)
  • lib/src/generated_protobuf/riak_yokozuna.pb.dart (Run dartfmt to format lib/src/generated_protobuf/riak_yokozuna.pb.dart.)
  • lib/src/generated_protobuf/riak_yokozuna.pbenum.dart (Run dartfmt to format lib/src/generated_protobuf/riak_yokozuna.pbenum.dart.)
  • lib/src/generated_protobuf/riak_yokozuna.pbserver.dart (Run dartfmt to format lib/src/generated_protobuf/riak_yokozuna.pbserver.dart.)

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.5.0 <3.0.0
meta ^1.1.7 1.1.8
pedantic ^1.8.0+1 1.9.0
protobuf ^1.0.0 1.0.1
Transitive dependencies
fixnum 0.10.11