Resource pooling service for LoopBack 4
npm install @loopback/poolingThis module contains a resource pooling service for LoopBack 4.
Some resources can be expensive to create/start. For example, a datasource has
overhead to connect to the database. There will be performance penalty to useTRANSIENT binding scope and creates a new instance per request. But it is not
feasible to be a singleton for some use cases, for example, each request may
have different security contexts.
The PoolingService is a singleton service to maintain a pool of resources.
This pool service can be bound to different keys to represent multiple pools.
Each binding is a singleton so that the state stays the same for injections into
multiple instances for other artifacts.
The pooling service observes life cycle events to start and stop.
The extension is built with
generic-pool.
> Experimental packages provide early access to advanced or experimental
> functionality to get community feedback. Such modules are published to npm
> using 0.x.y versions. Their APIs and functionality may be subject to
> breaking changes in future releases.
``sh`
npm install --save @loopback/pooling
Let's use the following class as an expensive resource that requires pooling for
performance.
`ts
class ExpensiveResource {
static id = 1;
id: number;
status: string;
constructor() {
this.status = 'created';
this.id = ExpensiveResource.id++;
}
}
`
`ts
import {Application, ContextTags} from '@loopback/core';
import {PoolingService, PoolServiceOptions} from '@loopback/pooling';
const app = new Application();
const poolingServiceBinding = app.service(PoolingService, {
[ContextTags.KEY]: 'services.MyPoolingService',
});
`
A pooling service has to be configured first. We must provide a factory that
handles create/destroy of resource instances to be pooled. There are also
options to control the pooling behavior.
`ts
app
.configure
.to({
factory: {
async create() {
const res = new ExpensiveResource();
return res;
},
async destroy(resource: ExpensiveResource) {
resource.status = 'destroyed';
},
},
{max: 16}, // Pooling options
});
`
See more details at
https://github.com/coopernurse/node-pool/blob/master/README.md#creating-a-pool.
`ts`
const myPoolingService = await app.get
'services.MyPoolingService',
);
`ts`
// The request context can be used by a factory to set up the acquired resource
// such as security credentials
const res1 = await myPoolingService.acquire(requestCtx);
// Do some work with res1
After the resource is used, it MUST be released back to the pool.
`ts`
myPoolingService.release(res1);
We can optionally implement life cycle methods for the factory and the resource
to provide additional logic for pooling life cycle events:
- create
- destroy
- acquire
- release
#### Factory level methods
`ts
const options: PoolingServiceOptions
factory: {
async create() {
const res = new ctor();
res.status = status;
if (status === 'invalid') {
// Reset status so that the next try will be good
status = 'created';
}
return res;
},
async destroy(resource: ExpensiveResource) {
resource.status = 'destroyed';
},
async validate(resource: ExpensiveResource) {
const result = resource.status === 'created';
resource.status = 'validated';
return result;
},
acquire(resource: ExpensiveResource, requestCtx: Context) {
resource.status = 'in-use-set-by-factory';
},
release(resource: ExpensiveResource) {
resource.status = 'idle-set-by-factory';
};
},
poolOptions,
};
`
#### Resource level methods
The resource can also implement similar methods:
`tscreate
class ExpensiveResourceWithHooks extends ExpensiveResource implements Poolable {
private requestCtx?: Context;
/**
* Life cycle method to be called by
*/
start() {
// In real world, this may take a few seconds to start
this.status = 'started';
}
/**
* Life cycle method to be called by destroy
*/
stop() {
this.status = 'stopped';
}
acquire(requestCtx: Context) {
this.status = 'in-use';
this.requestCtx = requestCtx;
}
release() {
this.status = 'idle';
this.requestCtx = undefined;
}
}
`
If the resource implements life cycle methods, they will be invoked for the
pooled resource.
- start: It will be called right after the resource is newly created by the
pool. This method should be used to initialize/start the resource.
- stop: It will be called when the pool is stopping/draining. This method
should be used to stop the resource.
- acquire: It will be called right after the resource is acquired from the
pool. If it fails, the resource will be destroyed from the pool. The method
should be used to set up the acquired resource.
- release: It will be called right before the resource is released back to the
pool. If it fails, the resource will be destroyed from the pool. The method
should be used to clean up the resource to be released.
The pooled resource can be wrapped into a provider class to provide pooled
instances.
`ts
import {PooledValue, PoolingService} from '@loopback/pooling';
class ExpensiveResourceProvider implements Provider<
PooledValue
> {
constructor(
@inject(POOL_SERVICE)
private poolingService: PoolingService
) {}
async value() {
return getPooledValue(this.poolingService);
}
}
`
Now we can bind the pooled resource provider:
`ts`
ctx.bind('resources.ExpensiveResource').toProvider(ExpensiveResourceProvider);
const res: PooledValue
'resources.ExpensiveResource',
);
// Do some work with the acquired resource
// The resource must be released back to the pool
await res.release();
We can leverage a binding as the factory to create resources for a pool.
`ts`
const MY_RESOURCE = BindingKey.create
ctx.bind(MY_RESOURCE).toClass(ExpensiveResource);
const factory = createPooledBindingFactory(MY_RESOURCE);
const poolBinding = createBindingFromClass(PoolingService, {
[ContextTags.KEY]: POOL_SERVICE,
});
ctx.add(poolBinding);
ctx.configure
factory,
});
Run npm test` from the root folder.
See
all contributors.
MIT