feat: fix complete interface, change resp to res, improve test coverage, add exists to buckets (#23)

* fix return type of task complete
* add file event worker
* change resp to res
* improve test coverage
* improve consistency of permissions
* fix late initialisation of workers
* consolidate channel handling

Author: HomelessDinosaur

README.md

@@ -34,9 +34,9 @@ The SDK is in early stage development and APIs and interfaces are still subject
 
 # Building a REST API with Nitric
 
-This guide will show you how to build a serverless REST API with the Nitric framework using Dart. The example API enables reading, writing and editing basic user profile information using a Nitric [collection](https://nitric.io/docs/collections) to store user data. Once the API is created we'll test it locally, then optionally deploy it to a cloud of your choice.
+This guide will show you how to build a serverless REST API with the Nitric framework using Dart. The example API enables reading, writing and editing basic user profile information using a Nitric [key value store](https://nitric.io/docs/keyvalue) to store user data. Once the API is created we'll test it locally, then optionally deploy it to a cloud of your choice.
 
-The example API enables reading, writing, and deleting profile information from a Nitric [collection](https://nitric.io/docs/collection).
+The example API enables reading, writing, and deleting profile information from a Nitric [key value store](https://nitric.io/docs/keyvalue).
 
 The API will provide the following routes:
 
@@ -72,10 +72,8 @@ dart create -t console my-profile-api
 Add the Nitric SDK by adding the repository URL to your `pubspec.yaml`.
 
 ```yaml
-nitric_sdk:
-  git:
-    url: https://github.com/nitrictech/dart-sdk.git
-    ref: main
+dependencies:
+  nitric_sdk: ^1.2.0
 ```
 
 Next, open the project in your editor of choice.
@@ -112,7 +110,7 @@ services:
 
 ## Create a Profile class
 
-We will create a class to represent the profiles that we will store in the collection. We will add `toJson` and `fromJson` functions to assist.
+We will create a class to represent the profiles that we will store in the key value store. We will add `toJson` and `fromJson` functions to assist.
 
 ```dart
 class Profile {
@@ -143,19 +141,18 @@ Applications built with Nitric can contain many APIs, let's start by adding one
 ```dart
 import 'package:nitric_sdk/nitric.dart';
 import 'package:nitric_sdk/resources.dart';
-import 'package:nitric_sdk/src/context/common.dart';
 
 import 'package:uuid/uuid.dart';
 
 void main() {
   // Create an API named 'public'
-  final profileApi = api("public");
+  final profileApi = Nitric.api("public");
 
-  // Define a key value store named 'profiles', then request getting, setting and deleting permissions.
-  final profiles = store("profiles").requires([
-    KeyValuePermission.getting,
-    KeyValuePermission.setting,
-    KeyValuePermission.deleting
+  // Define a key value store named 'profiles', then request get, set and delete permissions.
+  final profiles = Nitric.kv("profiles").allow([
+    KeyValuePermission.get,
+    KeyValuePermission.set,
+    KeyValuePermission.delete
   ]);
 }
 ```
@@ -188,7 +185,7 @@ profileApi.post("/profiles", (ctx) async {
 
   final profile = Profile.fromJson(ctx.req.json());
 
-  // Store the new profile in the profiles collection
+  // Store the new profile in the profiles kv store
   await profiles.set(id, profile);
 
   // Send a success response.
@@ -335,7 +332,7 @@ If you want to go a bit deeper and create some other resources with Nitric, why
 Define a bucket named `profilesImg` with reading/writing permissions.
 
 ```dart
-final profilesImg = Nitric.bucket("profilesImg").requires([BucketPermission.reading, BucketPermission.writing]);
+final profilesImg = Nitric.bucket("profilesImg").allow([BucketPermission.read, BucketPermission.write]);
 ```
 
 ### Get a URL to upload a profile image

analysis_options.yaml

@@ -15,17 +15,17 @@ include: package:lints/recommended.yaml
 
 # Uncomment the following section to specify additional rules.
 
-# linter:
-#   rules:
-#     - camel_case_types
+linter:
+  rules:
+    - camel_case_types
+    - unawaited_futures
 
 analyzer:
   exclude:
     - lib/**/*.pb.dart
     - lib/**/*.pbenum.dart
     - lib/**/*.pbgrpb.dart
     - lib/**/*.pbjson.dart
-
 # For more information about the core and recommended set of lints, see
 # https://dart.dev/go/core-lints
 

example/pubspec.yaml

@@ -7,7 +7,8 @@ environment:
   sdk: ^3.2.5
 
 dependencies:
-  nitric_sdk: ^1.0.0
+  nitric_sdk:
+    path: ../
   uuid: ^4.3.3
 
 dev_dependencies:

example/services/nitric_example.dart

@@ -21,26 +21,18 @@ class Profile {
 }
 
 void main() {
-  var oidc = Nitric.oidcRule(
-      "profile security",
-      "https://dev-w7gm5ldb.us.auth0.com",
-      ["https://test-security-definition/"]);
-
   // Create an API named 'public'
-  final profileApi = Nitric.api("public",
-      opts: ApiOptions(security: [
-        oidc(["user:read"])
-      ]));
+  final profileApi = Nitric.api("public");
 
   // Define a collection named 'profiles', then request reading and writing permissions.
-  final profiles = Nitric.store("profiles").requires([
-    KeyValueStorePermission.getting,
-    KeyValueStorePermission.deleting,
-    KeyValueStorePermission.setting
+  final profiles = Nitric.kv("profiles").allow([
+    KeyValueStorePermission.get,
+    KeyValueStorePermission.delete,
+    KeyValueStorePermission.set
   ]);
 
   final profilesImg = Nitric.bucket("profilesImg")
-      .requires([BucketPermission.reading, BucketPermission.writing]);
+      .allow([BucketPermission.read, BucketPermission.write]);
 
   profileApi.post("/profiles", (ctx) async {
     final uuid = Uuid();
@@ -53,10 +45,10 @@ void main() {
       await profiles.set(id, profile.toJson());
 
       // Send a success response.
-      ctx.resp.body = "Profile $id created.";
+      ctx.res.body = "Profile $id created.";
     } on Exception catch (e) {
-      ctx.resp.status = 400;
-      ctx.resp.body = "An error occurred: $e";
+      ctx.res.status = 400;
+      ctx.res.body = "An error occurred: $e";
     }
 
     return ctx;
@@ -68,11 +60,11 @@ void main() {
     try {
       // Retrieve and return the profile data
       final profile = await profiles.get(id);
-      ctx.resp.json(profile);
+      ctx.res.json(profile);
     } on Exception catch (e) {
       print(e);
-      ctx.resp.status = 404;
-      ctx.resp.body = "Profile $id not found.";
+      ctx.res.status = 404;
+      ctx.res.body = "Profile $id not found.";
     }
 
     return ctx;
@@ -84,10 +76,10 @@ void main() {
     // Delete the profile
     try {
       await profiles.delete(id);
-      ctx.resp.body = "Profile $id removed.";
+      ctx.res.body = "Profile $id removed.";
     } on Exception catch (e) {
-      ctx.resp.status = 404;
-      ctx.resp.body = "Profile $id not found. $e";
+      ctx.res.status = 404;
+      ctx.res.body = "Profile $id not found. $e";
     }
 
     return ctx;
@@ -124,8 +116,8 @@ void main() {
     final photoUrl =
         await profilesImg.file("images/$id/photo.png").getDownloadUrl();
 
-    ctx.resp.status = 303;
-    ctx.resp.headers["Location"] = [photoUrl];
+    ctx.res.status = 303;
+    ctx.res.headers["Location"] = [photoUrl];
 
     return ctx;
   });

lib/api.dart

@@ -1,3 +1,4 @@
 library;
 
 export 'src/nitric.dart';
+export 'src/context/common.dart';

lib/nitric.dart

@@ -1,2 +1 @@
-export 'src/resources/resources.dart';
-export 'src/context/common.dart';
+export 'src/resources/common.dart';

lib/resources.dart

@@ -1,28 +1,31 @@
 import 'dart:async';
 import 'dart:convert';
 
-import 'package:nitric_sdk/nitric.dart';
 import 'package:nitric_sdk/src/context/common.dart';
 import 'package:nitric_sdk/src/grpc_helper.dart';
 import 'package:nitric_sdk/src/nitric/proto/storage/v1/storage.pbgrpc.dart'
     as $p;
 import 'package:nitric_sdk/src/google/protobuf/duration.pb.dart' as $d;
 import 'package:fixnum/fixnum.dart';
-import 'package:grpc/grpc.dart';
+import 'package:nitric_sdk/src/workers/common.dart';
 
 class Bucket {
   late $p.StorageClient _storageClient;
+  late $p.StorageListenerClient? _storageListenerClient;
 
   String name;
 
-  Bucket(this.name, {$p.StorageClient? client}) {
+  Bucket(this.name,
+      {$p.StorageClient? client,
+      $p.StorageListenerClient? storageListenerClient}) {
     if (client == null) {
-      final channel = createClientChannelFromEnvVar();
-
-      _storageClient = $p.StorageClient(channel);
+      _storageClient =
+          $p.StorageClient(ClientChannelSingleton.instance.clientChannel);
     } else {
       _storageClient = client;
     }
+
+    _storageListenerClient = storageListenerClient;
   }
 
   /// Get a reference to a file by it's [key].
@@ -42,7 +45,7 @@ class Bucket {
 
   /// Create a blob event subscription triggered on the [blobEventType] filtered by files that match the [keyPrefixFilter].
   Future<void> on(BlobEventType blobEventType, String keyPrefixFilter,
-      BlobEventHandler handler) async {
+      FileEventHandler handler) async {
     // Create the request to register the Storage listener with the membrane
     final eventType = switch (blobEventType) {
       BlobEventType.write => $p.BlobEventType.Created,
@@ -55,9 +58,10 @@ class Bucket {
       blobEventType: eventType,
     );
 
-    var worker = BlobEventWorker(registrationRequest, handler, this);
+    var worker = FileEventWorker(registrationRequest, handler, this,
+        client: _storageListenerClient);
 
-    worker.start();
+    await worker.start();
   }
 }
 
@@ -149,50 +153,3 @@ class File {
     return resp.url;
   }
 }
-
-class BlobEventWorker implements Worker {
-  $p.RegistrationRequest registrationRequest;
-  BlobEventHandler middleware;
-  Bucket bucket;
-
-  BlobEventWorker(this.registrationRequest, this.middleware, this.bucket);
-
-  @override
-  Future<void> start() async {
-    // Create Storage listener client
-    final channel = createClientChannelFromEnvVar();
-    final client = $p.StorageListenerClient(channel);
-
-    final initMsg = $p.ClientMessage(registrationRequest: registrationRequest);
-
-    // Create the request stream and send the initial message
-    final requestStream = StreamController<$p.ClientMessage>();
-    requestStream.add(initMsg);
-
-    final response = client.listen(
-      requestStream.stream,
-    );
-
-    await for (final msg in response) {
-      if (msg.hasRegistrationResponse()) {
-        // Blob Notification has connected with Nitric server
-      } else if (msg.hasBlobEventRequest()) {
-        var ctx = BlobEventContext.fromRequest(msg, bucket);
-
-        try {
-          ctx = await middleware(ctx);
-        } on GrpcError catch (e) {
-          print("caught a GrpcError: $e");
-        } catch (e) {
-          print("unhandled application error: $e");
-
-          ctx.resp.success = false;
-        }
-
-        requestStream.add(ctx.toResponse());
-      }
-    }
-
-    await channel.shutdown();
-  }
-}

lib/src/api/bucket.dart

@@ -11,9 +11,8 @@ class KeyValueStore {
 
   KeyValueStore(this.name, {$p.KvStoreClient? client}) {
     if (client == null) {
-      var channel = createClientChannelFromEnvVar();
-
-      _keyValueClient = $p.KvStoreClient(channel);
+      _keyValueClient =
+          $p.KvStoreClient(ClientChannelSingleton.instance.clientChannel);
     } else {
       _keyValueClient = client;
     }

lib/src/api/keyvalue.dart

@@ -1,6 +1,6 @@
 import 'dart:async';
 
-import 'package:nitric_sdk/api.dart';
+import 'package:nitric_sdk/src/api/api.dart';
 import 'package:nitric_sdk/src/grpc_helper.dart';
 import 'package:nitric_sdk/src/nitric/proto/queues/v1/queues.pbgrpc.dart' as $p;
 
@@ -13,9 +13,8 @@ class Queue {
   /// Construct a new queue.
   Queue(this.name, {$p.QueuesClient? client}) {
     if (client == null) {
-      final channel = createClientChannelFromEnvVar();
-
-      _queuesClient = $p.QueuesClient(channel);
+      _queuesClient =
+          $p.QueuesClient(ClientChannelSingleton.instance.clientChannel);
     } else {
       _queuesClient = client;
     }
@@ -61,7 +60,7 @@ class DequeuedMessage {
   }
 
   /// Inform the queue that the message was handled successfully.
-  void complete() async {
+  Future<void> complete() async {
     var req =
         $p.QueueCompleteRequest(leaseId: _leaseId, queueName: _queue.name);