Skip to main content

Codec

Use codecs to implement protocols on top of lower-level ones.

A codec is a handler group that an adapter lists in its imports. It implements one of the conversion hooks the adapter loop resolves around every method call, so it sees each call go out and each answer come back without the caller knowing it is there:

Because each hook is looked up on the adapter's imported prototype chain, a codec delegates to the one beneath it with super.send / super.receive (or super.encode / super.decode), so several codecs can sit in one adapter and each layer is free to do only its own part. The hook is also resolved by specificity, not only by name: a codec may implement send, or a narrower <prefix>Send that the loop only reaches for the calls it matches — which is how the OpenAPI codec below stays out of the way of every operation that is not in its API definitions.

Which codec uses which hook​

The three HTTP codecs that ship with the framework are all handler groups under core/blong-gogo/src/codec/adapter/, and they show the two styles of hook side by side:

CodecFilesHooks it implements
codec.jsonrpcjsonrpc/send.ts, jsonrpc/receive.ts, errors.tssend builds the request — path from the method (/rpc/subject/object/predicate), a JSON-RPC 2.0 body, an id only for mtid: 'request', and expect / timeout carried from $meta. receive turns body.error into a thrown typed error and a non-2xx status into an HTTP error.
codec.openapiopenapi/load.ts, openapi/request.ts, openapi/ready.ts, openapi/errors.tsready merges the namespace definitions and builds one request handler per operation; requestSend dispatches by methodId($meta.method) and passes everything else straight through; responseReceive takes the body.
codec.mlemle/ready.tsready loads or generates the key pair; send refreshes the token first, adds the Authorization header and encrypts; receive decrypts error and result; errorReceive drops the token on a 401. The pre-auth login calls use their own senders (loginTokenCreateRequestSend, loginTokenRefreshRequestSend, …) that encrypt with the handshake keys, because those callers hold no token yet.

codec.mle is why the stack exists at all: every realm and suite that fronts the browser lists imports: ['codec.jsonrpc', 'codec.mle'] (core/blong-browser/adapter/backend.ts, realm/blong-test/browser.ts), and the encryption layer must come after the one that gives the call its JSON-RPC shape.

Configuration​

Codecs are configured by including their configuration in the adapter's configuration, while using their identifier (codec.xxx) as a key name. For example:

export default realm(() => ({
dev: {
http: {
'codec.openapi': {
namespace: {},
},
},
},
}));

HTTP codecs​

The HTTP codecs can be imported in the HTTP adapter, to implement specific functionality. They are implemented as a pair of send and receive handlers.

The framework includes the following commonly used HTTP codecs:

OpenAPI​

Import codec.openapi to enable easy calling of an external API, when it has OpenAPI or Swagger definition available. This usually happens at the server, when integrating with third party systems. The adapter can be called using an operationId from the API definition, prefixed with the namespace. Then this codec will determine the required HTTP method, path, headers and body for the request, based on the API definition. If operationId is not defined in the API, then it can be configured by merging an additional definition that specifies operationId for each HTTP method and path.

This codec has the following configuration:

namespace: # API definitions per namespace
time: # Namespace for the definitions
- some/path/world-time.yaml # OpenAPI/Swagger definition files
- some/path/world-time.operations.yaml
k8s: # Namespace for the definitions
- http://k8s.com/k8s-apps.json # OpenAPI/Swagger definition URLs
- http://k8s.com/k8s-discovery.json
- http://k8s.com/k8s-version.json

JSON-RPC​

The codec.jsonrpc can be imported in the HTTP adapter, to enable easy calling of the framework's JSON-RPC based APIs. This is usually done in the front end, but can be also used for other cases, like server to server calls. This codec will automatically determine the path for the called method, pass the parameters in the request body and process the response by returning the result or the error of the call.

Message Level Encryption​

The codec.mle can be imported in the HTTP adapter, to enable message level encryption when communicating with the framework's server. This codec must be put after codec.jsonrpc in the imports array.

TCP codecs​

The TCP codecs can be imported in the TCP adapter, to implement specific protocols. They are implemented as a pair of encode and decode handlers: encode turns the JavaScript object the adapter was called with into the Buffer the protocol expects, and decode turns the frames that come back into JavaScript objects. Because these protocols commonly multiplex, the pair also owns matching a response to the request that caused it.

No protocol-specific TCP codec ships as a reusable package today. The working example to follow is the Payshield adapter in test/framework/ctp/adapter/payshield/ — encode.ts and decode.ts over a bit-syntax header, plus payshieldSim.ts to stand in for the HSM — which is a framework test package rather than a supported codec: it is what this mechanism looks like when a real wire format is put through it.

ISO8583, SMPP and APTRA/NDC have no implementation in the repository. Treat them as the protocol motivations for the mechanism, not as codices you can import: writing one means writing the encode/decode pair for the wire format, and the Payshield pair is the shape to copy.