Mali

# 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 encapsulates the request of a call. Clients to not create this. Mali does it for us.

Response

Mali Response class that encapsulates 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

# new Mali(proto, name, options)

Create a gRPC service

Param Type Description
proto String | Object Optional 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.name : String

The service name. If multiple services are initialized, 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.silent : Boolean

Whether to supress logging errors in onerror. Default: false, that is errors will be logged to stderr.

Kind: instance property of Mali

# mali.addService(proto, name, options)

Add the service and initialize 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.

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 'getUser' in first service we find that has that call name.)

app.use('getUser', getUser)

Example (Define handler with middleware for RPC function 'getUser' in first service we find that has that call name.)

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

Example (Define handler with middleware for RPC function 'getUser' in service 'MyService'. We pick first service that matches the name.)

app.use('MyService', 'getUser', mw1, mw2, getUser)

Example (Define handler with middleware for rpc function 'getUser' in service 'MyService' with full package name.)

app.use('myorg.myapi.v1.MyService', 'getUser', mw1, mw2, getUser)

Example (Using destructuring define handlers for rpc functions 'getUser' and 'deleteUser'. Here we would match the first service that has a `getUser` RPC method.)

app.use({ getUser, deleteUser })

Example (Apply middleware to all handlers for a given service. We match first service that has the given name.)

app.use('MyService', mw1)

Example (Apply middleware to all handlers for a given service using full namespaced package name.)

app.use('myorg.myapi.v1.MyService', mw1)

Example (Using destructuring define handlers for RPC functions 'getUser' and 'deleteUser'. We match first service that has the given name.)

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

Example (Using destructuring define handlers for RPC functions 'getUser' and 'deleteUser'.)

// deleteUser has middleware mw1 and mw2
app.use({ 'myorg.myapi.v1.MyService': { getUser, deleteUser: [mw1, mw2, deleteUser] } })

Example (Multiple services using object notation.)

app.use(mw1) // global for all services
app.use('MyService', mw2) // applies to first matched service named 'MyService'
app.use({
  'myorg.myapi.v1.MyService': { // matches MyService
    sayGoodbye: handler1, // has mw1, mw2
    sayHello: [ mw3, handler2 ] // has mw1, mw2, mw3
  },
  'myorg.myapi.v1.MyOtherService': {
    saySomething: handler3 // only has mw1
  }
})

# mali.onerror(err)

Default error handler.

Kind: instance method of Mali

Param Type
err Error

# mali.start(port, creds, options) ⇒ Object

Start the service. All middleware and handlers have to be set up prior to calling start. Throws in case we fail to bind to the given port.

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()
options Object The start options to be passed to grpc.Server constructor.

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

# 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

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.locals : Object

Request-scoped local variables. You can place anything you wish here.

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 @malijs/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 encapsulates the request of a call. Clients to not create this. Mali does it for us.

Kind: global class

# 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 @malijs/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 @malijs/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 metadata 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 encapsulates the response of a call. Clients to not create this. Mali does it for us.

Kind: global class

# 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 @malijs/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 @malijs/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' })

Example (Custom Response Stream calls)

ctx.response.res = new Response({ object: true});
ctx.response.res.push({ data: 'hello 1' });
ctx.response.res.push({ data: 'hello 2' });
ctx.response.res.push({ data: 'hello 3' });
ctx.response.res.push(null);

# response.set(field, val)

Sets specific response header metadata 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 metadata 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