allserver 0.0.22 → 1.0.1

package/README.md

@@ -272,6 +272,44 @@ Allserver({
 }).start();
 ```
 
+#### Replying non-standard HTTP response from a procedure
+
+You'd need to deal with node.js `res` yourself.
+
+```js
+const procedures = {
+  processEntity({ someEntity }, ctx) {
+    const res = ctx.http.res;
+    res.statusCode = 422;
+    const msg = "Unprocessable Entity";
+    res.setHeader("Content-Length", Buffer.byteLength(msg));
+    res.send(msg);
+  },
+};
+```
+
+#### Accessing Node request and its raw body
+
+Occasionally, your HTTP method would need to access raw body of a request. This is how you do it:
+
+```js
+const procedures = {
+  async processEntity(_, ctx) {
+    const micro = ctx.allserver.transport.micro; // same as require("micro")
+    const req = ctx.http.req; // node.js Request
+    
+    // as a string
+    const text = await micro.text(req);
+    // as a node.js buffer
+    const buffer = await micro.buffer(req);
+    
+    // ... process the request here ... 
+  },
+};
+```
+
+More info can be found in the [`micro`](http://npmjs.com/package/micro) NPM module docs.
+
 ### HTTP server in AWS Lambda
 
 Doesn't require a dedicated client transport. Use the HTTP client below.
@@ -359,7 +397,7 @@ Yeah. This is a mutating call using `HTTP GET`. That's by design, and I love it.
 
 ### HTTP limitations
 
-1. Sub-routes are not available. E.g. you can't have `/users/updateUser`. (Yet.)
+1. Sub-routes are not well-supported, your procedure should be named `"users/updateUser"` or alike. Also, in the `AllserverClient` you'd want to use `nameMapper`.
 
 ### gRPC server side
 
@@ -446,31 +484,31 @@ const { success, code, message, user } = data;
 **All the arguments are optional.** But either `uri` or `transport` must be provided. We are trying to keep the highest possible DX here.
 
 - `uri`<br>
-The remote server address string. Out of box supported schemas are: `http`, `https`, `grpc`. (More to come.)
+  The remote server address string. Out of box supported schemas are: `http`, `https`, `grpc`. (More to come.)
 
 - `transport`<br>
-The transport implementation object. The `uri` is ignored if this option provided. If not given then it will be automatically created based on the `uri` schema. E.g. if it starts with `http://` or `https:/` then `HttpClientTransport` will be used. If starts with `grpc://` then `GrpcClientTransport` will be used.
+  The transport implementation object. The `uri` is ignored if this option provided. If not given then it will be automatically created based on the `uri` schema. E.g. if it starts with `http://` or `https:/` then `HttpClientTransport` will be used. If starts with `grpc://` then `GrpcClientTransport` will be used.
 
 - `neverThrow=true`<br>
-Set it to `false` if you want to get exceptions when there are a network, or a server errors during a procedure call. Otherwise, the standard `{success,code,message}` object is returned from method calls. The Allserver error `code`s are always start with `"ALLSERVER_"`. E.g. `"ALLSERVER_CLIENT_MALFORMED_INTROSPECTION"`.
+  Set it to `false` if you want to get exceptions when there are a network, or a server errors during a procedure call. Otherwise, the standard `{success,code,message}` object is returned from method calls. The Allserver error `code`s are always start with `"ALLSERVER_"`. E.g. `"ALLSERVER_CLIENT_MALFORMED_INTROSPECTION"`.
 
 - `dynamicMethods=true`<br>
-Automatically find (introspect) and call corresponding remote procedures. If set to `false` the `AllserverClient` would use only the `methods` you defined explicitly client-side.
+  Automatically find (introspect) and call corresponding remote procedures. If set to `false` the `AllserverClient` would use only the `methods` you defined explicitly client-side.
 
 - `autoIntrospect=true`<br>
-Do not automatically search (introspect) for remote procedures, instead use the runtime method names. This mean `AllserverClient` won't guarantee the procedure existence until you try calling the procedure. E.g., this code `allserverClient.myProcedureName()` will do `POST /myProcedureName` HTTP request (aka "call of faith"). Useful when you don't want to expose introspection HTTP endpoint or don't want to add Allserver's mandatory proto in GRPC server.
+  Do not automatically search (introspect) for remote procedures, instead use the runtime method names. This mean `AllserverClient` won't guarantee the procedure existence until you try calling the procedure. E.g., this code `allserverClient.myProcedureName()` will do `POST /myProcedureName` HTTP request (aka "call of faith"). Useful when you don't want to expose introspection HTTP endpoint or don't want to add Allserver's mandatory proto in GRPC server.
 
 - `callIntrospectedProceduresOnly=true`<br>
-If introspection couldn't find a procedure then do not attempt sending a "call of faith" to the server.
+  If introspection couldn't find a procedure then do not attempt sending a "call of faith" to the server.
 
 - `nameMapper`<br>
-A function to map/filter procedure names found on the server to something else. E.g. `nameMapper: name => _.toCamelCase(name)`. If "falsy" value is returned from `nameMapper()` then this procedure won't be added to the `AllserverClient` object instance, like if it was not found on the server.
+  A function to map/filter procedure names found on the server to something else. E.g. `nameMapper: name => _.toCamelCase(name)`. If "falsy" value is returned from `nameMapper()` then this procedure won't be added to the `AllserverClient` object instance, like if it was not found on the server.
 
 - `before`<br>
-The "before" client-side middleware(s). Can be either a function, or an array of functions.
+  The "before" client-side middleware(s). Can be either a function, or an array of functions.
 
 - `after`<br>
-The "after" client-side middleware(s). Can be either a function, or an array of functions.
+  The "after" client-side middleware(s). Can be either a function, or an array of functions.
 
 ### AllserverClient defaults
 
@@ -497,7 +535,10 @@ const httpClient = AllserverClient({ uri: "https://example.com" });
 You can add your own schema support to AllserverClient.
 
 ```js
-AllserverClient = AllserverClient.addTransport({ schema: "unixsocket", Transport: MyUnixSocketTransport });
+AllserverClient = AllserverClient.addTransport({
+  schema: "unixsocket",
+  Transport: MyUnixSocketTransport,
+});
 
 const client = AllserverClient({ uri: "unixsocket:///example/socket" });
 ```
@@ -505,9 +546,17 @@ const client = AllserverClient({ uri: "unixsocket:///example/socket" });
 You can overwrite the default client transport implementations:
 
 ```js
-HttpClientTransport = HttpClientTransport.props({ fetch: require("./fetch-retry") });
-AllserverClient = AllserverClient.addTransport({ schema: "http", Transport: HttpClientTransport });
-AllserverClient = AllserverClient.addTransport({ schema: "https", Transport: HttpClientTransport });
+HttpClientTransport = HttpClientTransport.props({
+  fetch: require("./fetch-retry"),
+});
+AllserverClient = AllserverClient.addTransport({
+  schema: "http",
+  Transport: HttpClientTransport,
+});
+AllserverClient = AllserverClient.addTransport({
+  schema: "https",
+  Transport: HttpClientTransport,
+});
 ```
 
 ## FAQ
@@ -657,7 +706,7 @@ const client = AllserverClient({
 
 ##### My authorisation is not supported. What should I do?
 
-If something more sophisticated is needed - you can have `before` and `after` middleware(s) which run client-side.
+If something more sophisticated is needed - you would need to mangle the `ctx` in the client `before` and `after` middlewares.
 
 ```js
 const { AllserverClient } = require("allserver");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "allserver",
-  "version": "0.0.22",
+  "version": "1.0.1",
   "description": "Multi-protocol simple RPC server and [optional] client. Boilerplate-less. Opinionated. Minimalistic. DX-first.",
   "main": "src/index.js",
   "scripts": {

package/src/server/Allserver.js

@@ -65,11 +65,12 @@ module.exports = require("stampit")({
             try {
                 result = await ctx.procedure(ctx.arg, ctx);
             } catch (err) {
-                this.logger.error("ALLSERVER_PROCEDURE_ERROR", err);
+                const code = err.code || "ALLSERVER_PROCEDURE_ERROR"
+                this.logger.error(code, err);
                 ctx.error = err;
                 ctx.result = {
                     success: false,
-                    code: err.code || "ALLSERVER_PROCEDURE_ERROR",
+                    code,
                     message: `'${err.message}' error in '${ctx.procedureName}' procedure`,
                 };
                 await this.transport.prepareProcedureErrorReply(ctx);
@@ -102,11 +103,12 @@ module.exports = require("stampit")({
                         break;
                     }
                 } catch (err) {
-                    this.logger.error("ALLSERVER_MIDDLEWARE_ERROR", err);
+                    const code = err.code || "ALLSERVER_MIDDLEWARE_ERROR";  
+                    this.logger.error(code, err);
                     ctx.error = err;
                     ctx.result = {
                         success: false,
-                        code: err.code || "ALLSERVER_MIDDLEWARE_ERROR",
+                        code,
                         message: `'${err.message}' error in '${middlewareType}' middleware`,
                     };
                     return;

package/src/server/HttpTransport.js

@@ -4,7 +4,7 @@ module.exports = require("./Transport").compose({
     name: "HttpTransport",
 
     props: {
-        _micro: require("micro"),
+        micro: require("micro"),
         port: process.env.PORT,
     },
 
@@ -14,11 +14,11 @@ module.exports = require("./Transport").compose({
 
     methods: {
         async _deserializeRequest(ctx) {
-            const bodyBuffer = await this._micro.buffer(ctx.http.req);
+            const bodyBuffer = await this.micro.buffer(ctx.http.req);
             let arg = ctx.http.query;
             try {
                 // If there is no body we will use request query (aka search params)
-                if (bodyBuffer.length !== 0) arg = await this._micro.json(ctx.http.req);
+                if (bodyBuffer.length !== 0) arg = await this.micro.json(ctx.http.req);
                 ctx.arg = arg;
                 return true;
             } catch (err) {
@@ -39,7 +39,7 @@ module.exports = require("./Transport").compose({
         },
 
         startServer(defaultCtx) {
-            this.server = this._micro(async (req, res) => {
+            this.server = this.micro(async (req, res) => {
                 const ctx = { ...defaultCtx, http: { req, res, url: parseUrl(req.url) } };
 
                 ctx.http.query = {};
@@ -78,7 +78,7 @@ module.exports = require("./Transport").compose({
 
         reply(ctx) {
             if (!ctx.http.statusCode) ctx.http.statusCode = 200;
-            this._micro.send(ctx.http.res, ctx.http.statusCode, ctx.result);
+            this.micro.send(ctx.http.res, ctx.http.statusCode, ctx.result);
         },
     },
 });