Skip to main content

Adapter

Blong includes the following commonly used adapters:

Adapter catalogue​

The drivers below are built into the runtime, in core/blong-gogo/src/adapter/server/, and each one is opt-in: an adapter is off until a layer attaches it. The namespace is chosen by the layer that attaches it, so the prefixes in this table are the conventions the repository's own suites and the blong-commander dev adapters use — a realm is free to pick another one.

AdapterNamespace and example triplesDriverExercised by
Kubernetescluster.* — cluster.pod.find, cluster.pod.log, cluster.namespace.list@kubernetes/client-nodetest/blong-int-adapter/k8s
Keycloakauth.* — auth.user.add, auth.realm.find, auth.token.create@keycloak/keycloak-admin-clienttest/blong-int-adapter/keycloak
S3 and S3-compatiblestorage.* — storage.bucket.list, storage.object.get, storage.object.add@aws-sdk/client-s3test/blong-int-adapter/s3
Vaultsecrets.* — secrets.secret.get, secrets.secret.write, secrets.mount.listnode-vaulttest/blong-int-adapter/vault
SQLsql.* — sql.<table>.find, sql.schema.list, sql.schemaTable.syncknex + mysql2test/blong-int-adapter/mysql
MongoDBmongo.* — mongo.collection.find, mongo.collection.add, mongo.database.listmongodbtest/blong-int-adapter/mongodb
Kafkabroker.* — broker.topic.list, broker.topic.findnode-rdkafkatest/blong-int-adapter/kafka
Redisredis.* — redis.key.get, redis.key.set, redis.hash.getAllioredistest/blong-int-adapter/redis
Slackslack.* — slack.message.send, slack.prompt.sendadapter.webhookrealm/blong-chat
GitHubgithub.* — github.release.get, github.release.create, github.release.listoctokitmanual
HTTPany namespace — the layer names itgottest/blong-int-adapter/http
TCPany namespace — a codec decides the payloadnode:net + ut-bitsyntaxtest/blong-sim-tcp/payshield
Webhook<namespace>Webhook.request, <namespace>Webhook.address, and the receiving half: listen, destinationgot + fastifyrealm/blong-chat

Two things are consistent across all of them. Credentials and connections belong to the adapter, so a handler never sees a token or an address: Vault logs in with AppRole and rotates its own token, the Kubernetes watcher owns the watch stream, and the S3 adapter owns the endpoint. And the driver's own shapes are translated into triples at that boundary — an object name becomes a bucket plus a key, a collection name becomes the table of a CRUD triple.

The class of a driver does not matter: Kubernetes, Keycloak, S3, Vault, Slack, GitHub, SQL, MongoDB, Kafka and Redis all reach the rest of the framework as the same thing, a handler that answers a semantic triple. See the adapter concept for what that boundary is for.

TCP​

Used for stream-based adapters.

To use them follow this pattern:

// realmname/adapter/adaptername.ts
import {adapter} from '@feasibleone/blong';

export default adapter<object>(api => ({
extends: 'adapter.tcp',
}));

TCP adapter configuration properties:

host: hsm.example.com # host to connect to
port: 1500 # port to connect to
listen: false # set to true to listen for connections
localPort: # port to listen for connections
socketTimeOut: # inactivity disconnect timeout
maxConnections: # maximum number of connections to accept
connectionDropPolicy: # which connections to drop
format:
size: 16/integer # the format of the size header
imports: ctp.payshield # codec name
ctp.payshield:
headerFormat: 6/string-left-zero # codec params
idleSend: 10000 # echo interval in milliseconds
maxReceiveBuffer: 4096 # maximum size in bytes of a single message
tls: # TLS config
ca: /some/path/ca.crt
cert: /some/path/tls.crt
key: /some/path/tls.key

HTTP​

Used for HTTP-based adapters.

// realmname/adapter/adaptername.ts
import {adapter} from '@feasibleone/blong';

export default adapter<object>(api => ({
extends: 'adapter.http',
}));

HTTP adapter configuration properties:

url: http://example.com # Base URL for all requests
tls: # TLS config
ca: /some/path/ca.crt
cert: /some/path/tls.crt
key: /some/path/tls.key
When using OpenAPI/Swagger definitions, make sure to include 'codec.openapi' in imports

property.

Configuration​

All adapters share some common configuration properties, such as:

  • logLevel - the log level for the adapter
  • namespace - prefixes used to call the adapter API
  • imports - handlers to attach in the adapter

See the configuration pattern for more details about the places where adapters can be configured.