API.md

Classes

Mali ⇐ Emitter

Represents a gRPC service

Context

Represents the application and call context. Clients to not create this. Mali does it for us.

Request

Mali Request class that encasulates the request of a call. Clients to not create this. Mali does it for us.

Response

Mali Response class that encasulates the response of a call. Clients to not create this. Mali does it for us.

Mali ⇐ Emitter

Represents a gRPC service

Kind: global class
Extends: Emitter

• Mali ⇐ Emitter
  • new Mali(proto, name, options)
  • .silent : Boolean
  • .name : String
  • .env : String
  • .ports : Array
  • .addService(proto, name, options)
  • .use(service, name, ...fns)
  • .onerror(err)
  • .start(port, creds) ⇒ Object
  • .close()
  • .toJSON() ⇒ Object
  • .inspect() ⇒ Object

new Mali(proto, name, options)

Create a gRPC service

Param	Type	Description
proto	String | Object	Path to the protocol buffer definition file - Object specifying root directory and file to load - Loaded grpc object - The static service proto object itself
name	Object	Optional name of the service or an array of names. Otherwise all services are used. In case of proto path the name of the service as defined in the proto definition. In case of proto object the name of the constructor.
options	Object	Options to be passed to grpc.load

Example (Create service dynamically)

const PROTO_PATH = path.resolve(__dirname, './protos/helloworld.proto')
const app = new Mali(PROTO_PATH, 'Greeter')

Example (Create service from static definition)

const services = require('./static/helloworld_grpc_pb')
const app = new Mali(services, 'GreeterService')

mali.silent : Boolean

Whether to log errors in onerror. Default: false

Kind: instance property of Mali

mali.name : String

The service name. If multiple services are initalized, this will be equal to the first service loaded.

Kind: instance property of Mali
Example

console.log(app.name) // 'Greeter'

mali.env : String

The environment. Taken from process.end.NODE_ENV. Default: development

Kind: instance property of Mali
Example

console.log(app.env) // 'development'

mali.ports : Array

The ports of the started service(s)

Kind: instance property of Mali
Example

console.log(app.ports) // [ 52239 ]

mali.addService(proto, name, options)

Add the service and initalizes the app with the proto. Basically this can be used if you don't have the data at app construction time for some reason. This is different than grpc.Server.addService().

Kind: instance method of Mali

Param	Type	Description
proto	String | Object	Path to the protocol buffer definition file - Object specifying root directory and file to load - Loaded grpc object - The static service proto object itself
name	Object	Optional name of the service or an array of names. Otherwise all services are used. In case of proto path the name of the service as defined in the proto definition. In case of proto object the name of the constructor.
options	Object	Options to be passed to grpc.load

mali.use(service, name, ...fns)

Define middleware and handlers. If service and name are given applies fns for that call under that service. If service name is provided and matches one of the services defined in proto, but no name is provided applies the fns as service level middleware for all handlers in that service. If service is provided and no name is provided, and service does not match any of the service names in the proto, assumes service is actually rpc call name. Uses 0th property in internal services object. Useful for protos with only one service. If an object is provided, you can set middleware and handlers for all services. If object provided but 0th key does not match any of the services in proto, we try to match the key to one of the rpc function names in one of the services. if we can't find the matching rpc function name just tries the 0th service name.

Kind: instance method of Mali

Param	Type	Description
service	String | Object	Service name
name	String | function	RPC name
...fns	function | Array	Middleware and/or handler

Example (Define handler for rpc function 'fn1')

app.use('fn1', fn1)

Example (Define handler with middleware for rpc function 'fn2')

app.use('fn2', mw1, mw2, fn2)

Example (Define handler with middleware for rpc function 'fn2' in service 'Service2')

app.use('Service2', 'fn2', mw1, mw2, fn2)

Example (Using destructuring define handlers for rpc functions 'fn1' and 'fn2')

app.use({ fn1, fn2 })

Example (Apply middleware to all handers for a service)

app.use('Service1', mw1)

Example (Using destructuring define handlers for rpc functions 'fn1' and 'fn2')

// fn2 has middleware mw1 and mw2
app.use({ MyService: { fn1, fn2: [mw1, mw2, fn2] } })

Example (Multiple services using object notation)

app.use(mw1) // global for all services
app.use('Service1', mw2) // applies to all Service1 handers
app.use({
  Service1: {
    sayGoodbye: handler1, // has mw1, mw2
    sayHello: [ mw3, handler2 ] // has mw1, mw2, mw3
  },
  Service2: {
    saySomething: handler3 // only has mw1
  }
})

mali.onerror(err)

Default error handler.

Kind: instance method of Mali

Param	Type
err	Error

mali.start(port, creds) ⇒ Object

Start the service. All middleware and handlers have to be set up prior to calling start.

Kind: instance method of Mali
Returns: Object - server - The grpc.Server instance

Param	Type	Description
port	String	The hostport for the service. Default: 127.0.0.1:0
creds	Object	Credentials options. Default: grpc.ServerCredentials.createInsecure()

Example

app.start('localhost:50051')

Example (Start same app on multiple ports)

app.start('127.0.0.1:50050')
app.start('127.0.0.1:50051')

mali.close()

Close the service(s).

Kind: instance method of Mali
Example

app.close()

mali.toJSON() ⇒ Object

Return JSON representation. We only bother showing settings.

Kind: instance method of Mali
Api: public

mali.inspect() ⇒ Object

Inspect implementation.

Kind: instance method of Mali

Context

Represents the application and call context. Clients to not create this. Mali does it for us.

Kind: global class
Summary: Represents a Mali call context

• Context
  • .name : String
  • .fullName : String
  • .service : String
  • .package : String
  • .app : Object
  • .call : Object
  • .request : Object
  • .response : Object
  • .req : Object | Stream
  • .type : String
  • .metadata : String
  • .get ⇒ *
  • .res : Object | Stream
  • .set : function
  • .sendMetadata : function
  • .getStatus ⇒ *
  • .setStatus : function

context.name : String

The call function name.

Kind: instance property of Context
Example

console.log(ctx.name) // 'SayHello'

context.fullName : String

The full name of the call.

Kind: instance property of Context
Example

console.log(ctx.fullName) // '/helloworld.Greeter/SayHello'

context.service : String

The service name of the call.

Kind: instance property of Context
Example

console.log(ctx.service) // 'Greeter'

context.package : String

The package name of the call.

Kind: instance property of Context
Example

console.log(ctx.package) // 'helloworld'

context.app : Object

The application instance reference.

Kind: instance property of Context

context.call : Object

The internal gRPC call instance reference. This is an alias to ctx.request.call.

Kind: instance property of Context

context.request : Object

The call's Mali Request object.

Kind: instance property of Context

context.response : Object

The call's Mali Response object.

Kind: instance property of Context

context.req : Object | Stream

The call request object or stream. This is an alias to ctx.request.res.

Kind: instance property of Context
Example

console.dir(ctx.req) // { name: 'Bob' }

context.type : String

The call's type. One of mali-call-types enums. This is an alias to ctx.request.type.

Kind: instance property of Context
Example

console.log(ctx.type) // 'unary'

Example

if(ctx.type === CallType.DUPLEX) {
  console.log('Duplex stream call')
}

context.metadata : String

The call's request metadata plain object. This is an alias to ctx.request.metadata.

Kind: instance property of Context
Example

console.log(ctx.metadata)
// { 'user-agent': 'grpc-node/1.7.1 grpc-c/1.7.1 (osx; chttp2)' }

context.get ⇒ *

Get request metadata value This is an alias to ctx.request.get().

Kind: instance property of Context
Returns: * - the metadata field value

Param	Type	Description
field	String	the field name

Example

console.log(ctx.get('user-agent'))
// 'grpc-node/1.7.1 grpc-c/1.7.1 (osx; chttp2)'

context.res : Object | Stream

The response object or stream. Should be set in handler. This is an alias to ctx.response.res.

Kind: instance property of Context
Example

ctx.res = { message: 'Hello World!' }

context.set : function

Set response header metadata value. This is an alias to ctx.response.set().

Kind: instance property of Context

Param	Type	Description
field	String | Object	the metadata field name or object for metadata
val	*	the value of the field

Example (Using string field name and value)

ctx.set('foo', 'bar')

Example (Using object)

ctx.set({
  foo: 'bar'
})

context.sendMetadata : function

Send response header metadata. This is an alias to ctx.response.sendMetadata().

Kind: instance property of Context

Param	Type	Description
md	Object	optional header metadata object to set into the request before sending if there is existing metadata in the response it is cleared if param is not provided sendMetadata sends the existing metadata in the response

Example (Set and send)

ctx.sendMetadata({
  foo: 'bar'
})

Example (Set and send later)

ctx.set('foo', 'bar')
// ... later
ctx.response.sendMetadata()

context.getStatus ⇒ *

Get response status / trailer metadata value. This is an alias to ctx.response.getStatus().

Kind: instance property of Context
Returns: * - the metadata field value console.log(ctx.getStatus('foo')) // 'bar'

Param	Type	Description
field	String	the field name

context.setStatus : function

Set response status / trailer metadata value. This is an alias to ctx.response.setStatus().

Kind: instance property of Context

Param	Type	Description
field	String | Object	the metadata field name or object for metadata
val	*	the value of the field

Example

ctx.setStatus('foo', 'bar')

Example (Using object)

ctx.setStatus({
  foo: 'bar'
})

Request

Mali Request class that encasulates the request of a call. Clients to not create this. Mali does it for us.

Kind: global class

• Request
  • new Request(call, type)
  • .call : Object
  • .req : Object | Stream
  • .metadata : Object
  • .type : String
  • .getMetadata() ⇒ Object
  • .get(field) ⇒ *

new Request(call, type)

Creates a Mali Request instance

Param	Type	Description
call	Object	the grpc call instance
type	String	the call type. one of mali-call-types enums.

request.call : Object

The internal gRPC call instance reference.

Kind: instance property of Request

request.req : Object | Stream

The call request object or stream.

Kind: instance property of Request
Example

console.log(ctx.request.req) // { name: 'Bob' }

request.metadata : Object

The call's request metadata plain object if present.

Kind: instance property of Request
Example

console.log(ctx.request.metadata)
// { 'user-agent': 'grpc-node/1.7.1 grpc-c/1.7.1 (osx; chttp2)' }

request.type : String

The call's type. One of mali-call-types enums.

Kind: instance property of Request
Example

console.log(ctx.request.type) // 'unary'

Example

if(ctx.request.type === CallType.DUPLEX) {
  console.log('Duplex stream call')
}

request.getMetadata() ⇒ Object

Gets the requests metadata as a grpc.Metadata object instance

Kind: instance method of Request
Returns: Object - request metadata

request.get(field) ⇒ *

Gets specific request meatadata field value

Kind: instance method of Request
Returns: * - the metadata value for the field

Param	Type	Description
field	*	the metadata field name

Example

console.log(ctx.request.get('foo')) // 'bar'

Response

Mali Response class that encasulates the response of a call. Clients to not create this. Mali does it for us.

Kind: global class

• Response
  • new Response(call, type)
  • .call : Object
  • .type : String
  • .metadata : Object
  • .status : Object
  • .res : Object | Stream
  • .set(field, val)
  • .get(field) ⇒ *
  • .getMetadata() ⇒ Object
  • .sendMetadata(md)
  • .getStatus(field) ⇒ *
  • .setStatus(field, val)
  • .getStatusMetadata() ⇒ Object

new Response(call, type)

Creates a Mali Response instance

Param	Type	Description
call	Object	the grpc call instance
type	String	the call type. one of mali-call-types enums.

response.call : Object

The internal gRPC call instance reference.

Kind: instance property of Response

response.type : String

The call's type. One of mali-call-types enums. This will match Request's type.

Kind: instance property of Response
Example

console.log(ctx.response.type) // 'unary'

response.metadata : Object

The call's response header metadata plain object if present.

Kind: instance property of Response
Example

ctx.response.set('foo', 'bar')
console.log(ctx.response.metadata)  // { 'foo': 'bar' }

response.status : Object

The call's response trailer / status metadata plain object if present.

Kind: instance property of Response
Example

ctx.response.setStatus('biz', 'baz')
console.log(ctx.response.status) // { biz: 'baz' }

response.res : Object | Stream

The call's response actual payload object / stream. In case of DUPLEX call this is automatically set the actual call instance.

Kind: instance property of Response
Example (UNARY or REQUEST STREAM calls)

ctx.response.res = { foo: 'bar' }

Example (RESPONSE STREAM calls)

ctx.response.res = createResponseStream()

Example (DUPLEX calls)

ctx.response.res.write({ foo: 'bar' })

response.set(field, val)

Sets specific response header meatadata field value

Kind: instance method of Response

Param	Type	Description
field	String | Object	the metadata field name or object for metadata
val	*	the value of the field

Example (Using string field name and value)

ctx.response.set('foo', 'bar')

Example (Using object)

ctx.response.set({
  foo: 'bar'
})

response.get(field) ⇒ *

Gets the response header metadata value

Kind: instance method of Response
Returns: * - the metadata field value

Param	Type	Description
field	String	the field name

Example

console.log(ctx.response.get('foo')) // 'bar'

response.getMetadata() ⇒ Object

Gets the response metadata as a grpc.Metadata object instance

Kind: instance method of Response
Returns: Object - response metadata

response.sendMetadata(md)

Sends the response header metadata. Optionally (re)sets the header metadata as well.

Kind: instance method of Response

Param	Type	Description
md	Object	optional header metadata object to set into the request before sending if there is existing metadata in the response it is cleared if param is not provided sendMetadata sends the existing metadata in the response

Example (Set and send)

ctx.response.sendMetadata({
  foo: 'bar'
})

Example (Set and send later)

ctx.response.set('foo', 'bar')
// ... later
ctx.response.sendMetadata()

response.getStatus(field) ⇒ *

Gets the response status / trailer metadata value

Kind: instance method of Response
Returns: * - the metadata field value

Param	Type	Description
field	String	the field name

Example

console.log(ctx.response.getStatus('bar')) // 'baz'

response.setStatus(field, val)

Sets specific response status / trailer meatadata field value

Kind: instance method of Response

Param	Type	Description
field	String | Object	the metadata field name or object for metadata
val	*	the value of the field

Example (Using string field name and value)

ctx.response.setStatus('foo', 'bar')

Example (Using object)

ctx.response.setStatus({
  foo: 'bar'
})

response.getStatusMetadata() ⇒ Object

Gets the response status / trailer metadata as a grpc.Metadata object instance

Kind: instance method of Response
Returns: Object - response status / trailer metadata