https://github.com/loopbackio/loopback-connector-grpc
LoopBack connector for gRPC (experimental)
https://github.com/loopbackio/loopback-connector-grpc
Last synced: 9 months ago
JSON representation
LoopBack connector for gRPC (experimental)
- Host: GitHub
- URL: https://github.com/loopbackio/loopback-connector-grpc
- Owner: loopbackio
- License: other
- Created: 2016-12-15T21:11:29.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-12-15T05:13:21.000Z (about 2 years ago)
- Last Synced: 2025-04-19T18:16:42.133Z (9 months ago)
- Language: JavaScript
- Homepage:
- Size: 168 KB
- Stars: 16
- Watchers: 28
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# loopback-connector-grpc
[](https://github.com/loopbackio/loopback-connector-grpc/actions/workflows/ci.yaml)
[](https://app.travis-ci.com/loopbackio/loopback-connector-grpc)
[](https://coveralls.io/github/loopbackio/loopback-connector-grpc?branch=master)
The gRPC connector enables LoopBack applications to interact with [gRPC](http://www.grpc.io/) services.
## Installation
In your application root directory, enter:
```
$ npm install loopback-connector-grpc --save
```
This will install the module from npm and add it as a dependency to the application's `package.json` file.
## Configuration
To interact with a gRPC API, configure a data source backed by the gRPC connector:
With code:
```javascript
var ds = loopback.createDataSource('grpc', {
connector: 'loopback-connector-grpc',
spec: 'note.proto',
});
```
With JSON in `datasources.json` (for example, with basic authentication):
```
"gRPCDataSource": {
"name": "gRPCDataSource",
"connector": "grpc",
"spec": "note.proto",
"security": {
"type" : "basic",
"username": "the user name",
"password": "thepassword"
}
```
## Data source properties
Specify the options for the data source with the following properties.
| Property | Description | Default |
|----------|-------------|-----------|
| connector | Must be `'loopback-connector-grpc'` to specify gRPC connector| None |
|spec | HTTP URL or path to the gRPC specification file (with file name extension `.yaml/.yml` or `.json`). File path must be relative to current working directory (`process.cwd()`).| None |
|validate | When `true`, validates provided `spec` against gRPC specification 2.0 before initializing a data source. | `false`|
| security | Security configuration for making authenticated requests to the API. | None |
### Authentication
Basic authentication:
```javascript
security: {
rootCerts: 'rootCerts.crt', // Path to root certs
key: 'gprc.key', // Path to client SSL private key
cert: 'grpc.crt' // Path to client SSL certificate
}
```
### Creating a model from the gRPC data source
The gRPC connector loads the API specification document asynchronously. As a result, the data source won't be ready to create models until it is connected. For best results, use an event handler for the `connected` event of data source:
```javascript
ds.once('connected', function(){
var PetService = ds.createModel('PetService', {});
...
});
```
Once the model is created, all available gRPC API operations can be accessed as model methods, for example:
```javascript
...
PetService.getPetById({petId: 1}, function (err, res){
...
});
```
The model methods can also be called as promises:
```javascript
PetService.getPetById({petId: 1}).then(function(res) {
...
}, function(err) {
...
});
// in async/await flavor
const res = await PetService.getPetById({petId: 1});
```
### Extend a model to wrap/mediate API Operations
Once you define the model, you can wrap or mediate it to define new methods. The following example simplifies the `getPetById` operation to a method that takes `petID` and returns a Pet instance.
```javascript
PetService.searchPet = function(petID, cb){
PetService.getPetById({petId: petID}, function(err, res){
if(err) cb(err, null);
var result = res.data;
cb(null, result);
});
};
```
This custom method on the `PetService` model can be exposed as REST API end-point. It uses `loopback.remoteMethod` to define the mappings:
```javascript
PetService.remoteMethod(
'searchPet', {
accepts: [
{ arg: 'petID', type: 'string', required: true,
http: { source: 'query' }
}
],
returns: {arg: 'result', type: 'object', root: true },
http: {verb: 'get', path: '/searchPet'}
}
);
```
### Example
Coming soon...