@edd-kernel/provider-gcp-pub-sub
v0.2.0-alpha.1
Published
Google Cloud Pub/Sub EDD Kernel provider.
Maintainers
Readme
@edd-kernel/provider-gcp-pub-sub
Google Cloud Pub/Sub provider for EDD Kernel.
This package belongs to the EDD Kernel provider layer. It owns only the Google
Cloud Pub/Sub transport mapping for the shared @edd-kernel/contracts client
contract.
Repository: brunnofoggia/edd-kernel-js
Install
npm install @edd-kernel/contracts @edd-kernel/provider-gcp-pub-subFor provider-name based client creation, install @edd-kernel/factory in place of the
contract. It brings the contract and re-exports it:
npm install @edd-kernel/factory @edd-kernel/provider-gcp-pub-subUsage
import { createGcpPubSubClient } from '@edd-kernel/provider-gcp-pub-sub';
const client = createGcpPubSubClient(
{ createIfNotExists: true },
{
projectId: 'my-project',
bindings: [{ topic: 'email-events', subscriptions: ['email-workers'] }],
},
);
await client.send({ topicName: 'email-events' }, { type: 'EmailRequested', payload: {} });
await client.consume({ subscriptionName: 'email-workers' }, async (event, context) => {
console.log(event);
await context.ack();
});You can also create this provider through @edd-kernel/factory:
import { EddProviderName, createEddClient } from '@edd-kernel/factory';
const client = await createEddClient({
providerName: EddProviderName.GcpPubSub,
createIfNotExists: true,
options: {
projectId: 'my-project',
bindings: [{ topic: 'email-events', subscriptions: ['email-workers'] }],
},
});The package also exports GcpPubSubEddClient for direct construction and
inheritance. Its static provider identity is gcp-pub-sub.
Addressing
| Type | Address | Meaning |
| ---------------------- | ---------------------- | ---------------------------------------------------------------- |
| GcpPubSubEventTarget | { topicName } | A logical topic name, joined with env, project and prefix. |
| GcpPubSubEventTarget | { topicPath } | projects/{project}/topics/{topic}, used as it is. |
| GcpPubSubEventQueue | { subscriptionName } | A logical subscription name, scoped the same way. |
| GcpPubSubEventQueue | { subscriptionPath } | projects/{project}/subscriptions/{id}, used as it is. |
Any other address is refused by the compiler, and at runtime with
EddKernelConfigurationError.
When createIfNotExists creates a subscription, it binds to the topic its binding
names, or to the topic of the same name. createSubscription(name, { topicName }) names
the topic in the call, ahead of both. Both sides of a binding are logical names, scoped
like any address and with the same options as the subscription.
A subscription addressed by subscriptionPath is never created: a path has no logical
name to look a binding up by. One that exists is consumed as usual.
A subscription cannot move to another topic. One that already exists on a topic other
than the expected one raises EddKernelConfigurationError when the consumer starts, instead
of consuming from a topic nobody publishes to. Delete it and it is created again on the
right topic.
A topic or subscription another client creates at the same moment counts as present, so two applications starting together on one topic both come up.
Provider Options
publisher: custom Pub/Sub publisher-like client for tests or adapters.subscriber: custom Pub/Sub subscriber-like client for tests or adapters.clientOptions: options used to create default Google Pub/Sub v1 clients.credentials: service account credentials object passed to default Google Pub/Sub v1 clients.projectId: project used when short topic or subscription names are provided.bindings: each topic and the subscriptions that read it, as{ topic, subscriptions }entries. A topic may appear in several entries; a subscription bound to two topics is refused when the client is built.pullTimeoutMs: deadline for each long-poll request, defaulting to5000.pollIntervalMs: delay between empty polling cycles.nackAckDeadlineSeconds: ack deadline applied onnack, defaulting to0, which redelivers at once.
If both credentials and clientOptions.credentials are provided,
credentials takes precedence.
Pull requests omit the deprecated returnImmediately field and use the Pub/Sub
long-polling behavior. A pull deadline is treated as an empty polling cycle so
idle consumers can stop promptly.
Acknowledgement
ack()calls Pub/Subacknowledge.nack()callsmodifyAckDeadlinewithackDeadlineSeconds: 0.autoAck: truestill performs a manual acknowledgement operation.
The provider uses finite pull requests for the base consume behavior. It does
not use the high-level streaming subscription API for the portable contract.
Runtime polling failures are logged and retried after pollIntervalMs. Stopping
a consumer waits for active handlers, and closing the client stops and drains
all consumers before releasing transport resources. Only publisher and
subscriber clients created internally by the kernel are closed; injected
clients remain application-owned. Both operations are idempotent.
