Async operations

f3ath · f3ath · commit 72513b918ff0 · 2019-03-21T01:09:56.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,8 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - More BC-breaking changes in the Server
 
+### Fixed
+- Location headers were incorrectly generated by Server
+
 ### Added
 - Related collection pagination
+- Async operations support
 
 ## [0.4.0] - 2019-03-17
 ### Changed
diff --git a/README.md b/README.md
@@ -1,11 +1,9 @@
-# Implementation of [JSON:API v1.0](http://jsonapi.org) in Dart
+# Implementation of [{json:api} v1.0](http://jsonapi.org) in Dart
+[{json:api} v1.0](http://jsonapi.org) is a specification for building APIs in JSON. This library implements 
+a Client (VM, Flutter, Web), and a Server (VM only).
 
-## Warning! This is a work-in-progress. While at v0, the API is changing rapidly.
 
-### Feature roadmap
-The features here are roughly ordered by priority. Feel free to open an issue if you want to add another feature.
-
-#### Client
+## Client
 - [x] Fetching single resources and resource collections
 - [x] Collection pagination
 - [x] Fetching relationships and related resources and collections
@@ -17,8 +15,7 @@ The features here are roughly ordered by priority. Feel free to open an issue if
 - [x] Updating relationships
 - [x] Compound documents
 - [x] Related collection pagination
-- [ ] Asynchronous processing 
-- [ ] Optional check for `Content-Type` header in incoming responses 
+- [x] Asynchronous processing 
 
 #### Server
 - [x] Fetching single resources and resource collections
@@ -30,21 +27,18 @@ The features here are roughly ordered by priority. Feel free to open an issue if
 - [x] Updating resource's attributes
 - [x] Updating resource's relationships
 - [x] Updating relationships
-- [ ] Compound documents
-- [ ] Sparse fieldsets 
-- [ ] Sorting, filtering
-- [ ] Related collection pagination
-- [ ] Asynchronous processing 
-- [ ] Optional check for `Content-Type` header in incoming requests 
-- [ ] Support annotations in resource mappers (?) 
+- [x] Related collection pagination
+- [x] Compound documents
+- [x] Asynchronous processing 
 
 #### Document
 - [x] Support relationship objects lacking the `data` member
 - [x] Compound documents
 - [ ] Support `meta` members
 - [ ] Support `jsonapi` members
-- [ ] Structural Validation including compound documents
+- [ ] Structural Validation including compound documents and sparse fieldsets
 - [ ] Naming Validation
+- [ ] Meaningful parsing exceptions
 - [ ] JSON:API v1.1 features
 
 ### Usage
diff --git a/example/README.md b/example/README.md
@@ -1,13 +1,11 @@
 # JSON:API examples
 
 ## [Cars Server](./cars_server)
-This is a simple JSON:API server which is used in the tests. It provides an API to a collection to car companies ad models.
+This is a simple JSON:API server which is used in the tests. It provides an API to a collection to car companies and models.
 You can run it locally to play around.
 
 - In you console run `dart example/cars_server.dart`, this will start the server at port 8080.
 - Open http://localhost:8080/companies in the browser.
 
-**Warning: Server API is not stable yet!**
-
 ## [Cars Client](./cars_client.dart)
 A simple client for Cars Server API. It is also used in the tests.
diff --git a/example/cars_server.dart b/example/cars_server.dart
@@ -46,8 +46,12 @@ Future<HttpServer> createServer(InternetAddress addr, int port) async {
     Company('4')..name = 'Toyota',
   ].forEach(companies.insert);
 
-  final controller = CarsController(
-      {'companies': companies, 'cities': cities, 'models': models});
+  final controller = CarsController({
+    'companies': companies,
+    'cities': cities,
+    'models': models,
+    'jobs': JobDAO()
+  });
 
   final urlDesign = StandardURLDesign(Uri.parse('http://localhost:$port'));
 
@@ -64,14 +68,15 @@ Future<HttpServer> createServer(InternetAddress addr, int port) async {
 class Url {
   static final _design = StandardURLDesign(Uri.parse('http://localhost:8080'));
 
-  static collection(String type) => _design.collection(CollectionTarget(type));
+  static Uri collection(String type) =>
+      _design.collection(CollectionTarget(type));
 
-  static resource(String type, String id) =>
+  static Uri resource(String type, String id) =>
       _design.resource(ResourceTarget(type, id));
 
-  static related(String type, String id, String relationship) =>
+  static Uri related(String type, String id, String relationship) =>
       _design.related(RelatedTarget(type, id, relationship));
 
-  static relationship(String type, String id, String relationship) =>
+  static Uri relationship(String type, String id, String relationship) =>
       _design.relationship(RelationshipTarget(type, id, relationship));
 }
diff --git a/example/cars_server/controller.dart b/example/cars_server/controller.dart
@@ -7,6 +7,7 @@ import 'package:json_api/src/server/request_target.dart';
 import 'package:uuid/uuid.dart';
 
 import 'dao.dart';
+import 'job_queue.dart';
 
 class CarsController implements JsonApiController {
   final Map<String, DAO> _dao;
@@ -75,14 +76,19 @@ class CarsController implements JsonApiController {
       return response
           .errorNotFound([JsonApiError(detail: 'Unknown resource type')]);
     }
-    final res =
-        _dao[request.target.type].fetchByIdAsResource(request.target.id);
-    if (res == null) {
+    final obj = _dao[request.target.type].fetchById(request.target.id);
+
+    if (obj == null) {
       return response
           .errorNotFound([JsonApiError(detail: 'Resource not found')]);
     }
+    if (obj is Job && obj.resource != null) {
+      return response.sendSeeOther(obj.resource);
+    }
+
     final fetchById = (Identifier _) => _dao[_.type].fetchByIdAsResource(_.id);
 
+    final res = _dao[request.target.type].toResource(obj);
     final children = res.toOne.values
         .map(fetchById)
         .followedBy(res.toMany.values.expand((_) => _.map(fetchById)));
@@ -167,7 +173,19 @@ class CarsController implements JsonApiController {
         attributes: request.payload.attributes,
         toMany: request.payload.toMany,
         toOne: request.payload.toOne));
+
+    if (request.target.type == 'models') {
+      // Insertion is artificially delayed
+      final job = Job(Future.delayed(Duration(milliseconds: 100), () {
+        _dao[request.target.type].insert(created);
+        return _dao[request.target.type].toResource(created);
+      }));
+      _dao['jobs'].insert(job);
+      return response.sendAccepted(_dao['jobs'].toResource(job));
+    }
+
     _dao[request.target.type].insert(created);
+
     return response.sendCreated(_dao[request.target.type].toResource(created));
   }
 
diff --git a/example/cars_server/dao.dart b/example/cars_server/dao.dart
@@ -1,6 +1,7 @@
 import 'package:json_api/document.dart';
 import 'package:json_api/src/nullable.dart';
 
+import 'job_queue.dart';
 import 'model.dart';
 
 abstract class DAO<T> {
@@ -162,3 +163,16 @@ class CompanyDAO extends DAO<Company> {
     throw ArgumentError();
   }
 }
+
+class JobDAO extends DAO<Job> {
+  @override
+  Job create(Resource resource) {
+    throw UnsupportedError('Jobs are created internally');
+  }
+
+  @override
+  void insert(Job job) => _collection[job.id] = job;
+
+  @override
+  Resource toResource(Job job) => Resource('jobs', job.id);
+}
diff --git a/example/cars_server/job_queue.dart b/example/cars_server/job_queue.dart
@@ -0,0 +1,15 @@
+import 'dart:async';
+
+import 'package:json_api/document.dart';
+import 'package:uuid/uuid.dart';
+
+class Job {
+  final String id;
+
+  String get status => resource == null ? 'pending' : 'complete';
+  Resource resource;
+
+  Job(Future<Resource> create) : id = Uuid().v4() {
+    create.then((_) => this.resource = _);
+  }
+}
diff --git a/lib/src/client/client.dart b/lib/src/client/client.dart
@@ -5,6 +5,7 @@ import 'package:http/http.dart' as http;
 import 'package:json_api/document.dart';
 import 'package:json_api/parser.dart';
 import 'package:json_api/src/client/response.dart';
+import 'package:json_api/src/client/status_code.dart';
 import 'package:json_api/src/nullable.dart';
 
 typedef Document ResponseParser(Object j);
@@ -180,8 +181,14 @@ class JsonApiClient {
         return Response(r.statusCode, r.headers);
       }
       final body = json.decode(r.body);
-      final document = body == null ? null : _parser.parseDocument(body, parse);
-      return Response(r.statusCode, r.headers, document: document);
+      if (StatusCode(r.statusCode).isPending) {
+        return Response(r.statusCode, r.headers,
+            asyncDocument: body == null
+                ? null
+                : _parser.parseDocument(body, _parser.parseResourceData));
+      }
+      return Response(r.statusCode, r.headers,
+          document: body == null ? null : _parser.parseDocument(body, parse));
     } finally {
       client.close();
     }
diff --git a/lib/src/client/response.dart b/lib/src/client/response.dart
@@ -1,7 +1,8 @@
 import 'package:json_api/document.dart';
 import 'package:json_api/src/client/status_code.dart';
+import 'package:json_api/src/nullable.dart';
 
-/// A response returned by JSON:API cars_server
+/// A response returned by JSON:API client
 class Response<Data extends PrimaryData> {
   /// HTTP status code
   final int status;
@@ -10,32 +11,46 @@ class Response<Data extends PrimaryData> {
   /// May be null.
   final Document<Data> document;
 
+  /// The document received with `202 Accepted` response (if any)
+  /// https://jsonapi.org/recommendations/#asynchronous-processing
+  final Document<ResourceData> asyncDocument;
+
   /// Headers returned by the server.
   final Map<String, String> headers;
 
-  Response(this.status, this.headers, {this.document}) {
-    // TODO: Check for null and content-type
-  }
+  Response(this.status, this.headers, {this.document, this.asyncDocument});
 
   /// Primary Data from the document (if any)
   Data get data => document.data;
 
+  /// Primary Data from the async document (if any)
+  ResourceData get asyncData => asyncDocument.data;
+
   /// Was the request successful?
   ///
-  /// For pending (202 Accepted) requests [isSuccessful] is always false.
+  /// For pending (202 Accepted) requests both [isSuccessful] and [isFailed]
+  /// are always false.
   bool get isSuccessful => StatusCode(status).isSuccessful;
 
-  /// Is a request is accepted but not finished yet (e.g. queued) [isPending] is true.
-  /// HTTP Status 202 Accepted should be returned for pending requests.
-  /// The "Content-Location" header should have a link to the job queue and
-  /// [document] should contain a queued job resource object.
+  /// This property is an equivalent of `202 Accepted` HTTP status.
+  /// It indicates that the request is accepted but not finished yet (e.g. queued).
+  /// The [contentLocation] should have a link to the job queue resource and
+  /// [asyncData] may contain a queued job resource object.
   ///
   /// See: https://jsonapi.org/recommendations/#asynchronous-processing
-  bool get isPending => StatusCode(status).isPending;
+  bool get isAsync => StatusCode(status).isPending;
 
   /// Any non 2** status code is considered a failed operation.
   /// For failed requests, [document] is expected to contain [ErrorDocument]
   bool get isFailed => StatusCode(status).isFailed;
 
-  String get location => headers['location'];
+  /// The `Location` HTTP header value. For `201 Created` responses this property
+  /// contains the location of a newly created resource.
+  Uri get location => nullable(Uri.parse)(headers['location']);
+
+  /// The `Content-Location` HTTP header value. For `202 Accepted` responses
+  /// this property contains the location of the Job Queue resource.
+  ///
+  /// More details: https://jsonapi.org/recommendations/#asynchronous-processing
+  Uri get contentLocation => nullable(Uri.parse)(headers['content-location']);
 }
diff --git a/lib/src/server/controller.dart b/lib/src/server/controller.dart
@@ -62,6 +62,8 @@ abstract class ControllerResponse {
   final headers = <String, String>{};
 
   Future<void> errorNotFound(Iterable<JsonApiError> errors);
+
+  Future<void> errorBadRequest(Iterable<JsonApiError> errors);
 }
 
 abstract class FetchCollectionResponse extends ControllerResponse {
@@ -74,9 +76,14 @@ abstract class CreateResourceResponse extends ControllerResponse {
   Future<void> sendNoContent();
 
   Future<void> errorConflict(Iterable<JsonApiError> errors);
+
+  Future<void> sendAccepted(Resource asyncJob);
 }
 
 abstract class FetchResourceResponse extends ControllerResponse {
+  /// https://jsonapi.org/recommendations/#asynchronous-processing
+  Future<void> sendSeeOther(Resource resource);
+
   Future<void> sendResource(Resource resource, {Iterable<Resource> included});
 }
 
@@ -91,6 +98,8 @@ abstract class UpdateResourceResponse extends ControllerResponse {
 
   Future<void> sendNoContent();
 
+  Future<void> sendAccepted(Resource asyncJob);
+
   Future<void> errorConflict(Iterable<JsonApiError> errors);
 
   Future<void> errorForbidden(Iterable<JsonApiError> errors);
@@ -105,6 +114,8 @@ abstract class FetchRelationshipResponse extends ControllerResponse {
 abstract class ReplaceToOneResponse extends ControllerResponse {
   Future<void> sendNoContent();
 
+  Future<void> sendAccepted(Resource asyncJob);
+
   Future<void> sendToMany(Iterable<Identifier> collection);
 
   Future<void> sendToOne(Identifier id);
@@ -113,12 +124,16 @@ abstract class ReplaceToOneResponse extends ControllerResponse {
 abstract class ReplaceToManyResponse extends ControllerResponse {
   Future<void> sendNoContent();
 
+  Future<void> sendAccepted(Resource asyncJob);
+
   Future<void> sendToMany(Iterable<Identifier> collection);
 
   Future<void> sendToOne(Identifier id);
 }
 
 abstract class AddToManyResponse extends ControllerResponse {
+  Future<void> sendAccepted(Resource asyncJob);
+
   Future<void> sendToMany(Iterable<Identifier> collection);
 }
 
diff --git a/lib/src/server/document_builder.dart b/lib/src/server/document_builder.dart
@@ -6,29 +6,37 @@ import 'package:json_api/src/server/request_target.dart';
 /// of building response documents and is responsible for such aspects as
 ///  adding `meta` and `jsonapi` attributes and generating links
 abstract class DocumentBuilder {
+  /// A collection of (primary) resources
   Document<ResourceCollectionData> collection(
       Collection<Resource> collection, CollectionTarget target, Uri self,
       {Iterable<Resource> included});
 
+  /// A single (primary) resource
   Document<ResourceData> resource(
       Resource resource, ResourceTarget target, Uri self,
       {Iterable<Resource> included});
 
+  /// A collection of related resources
   Document<ResourceCollectionData> relatedCollection(
       Collection<Resource> resources, RelatedTarget target, Uri self,
       {Iterable<Resource> included});
 
+  /// A single related resource
   Document<ResourceData> relatedResource(
       Resource resource, RelatedTarget target, Uri self,
       {Iterable<Resource> included});
 
+  /// A to-many relationship
   Document<ToMany> toMany(
       Iterable<Identifier> collection, RelationshipTarget target, Uri self);
 
+  /// A to-one relationship
   Document<ToOne> toOne(
       Identifier identifier, RelationshipTarget target, Uri self);
 
+  /// A document containing just a meta member
   Document meta(Map<String, Object> meta);
 
+  /// A document containing a list of errors
   Document error(Iterable<JsonApiError> errors);
 }
diff --git a/lib/src/server/numbered_page.dart b/lib/src/server/numbered_page.dart
diff --git a/lib/src/server/server.dart b/lib/src/server/server.dart
diff --git a/lib/src/server/standard_document_builder.dart b/lib/src/server/standard_document_builder.dart
diff --git a/test/functional/create_test.dart b/test/functional/create_test.dart
diff --git a/test/functional/fetch_test.dart b/test/functional/fetch_test.dart
