Connectors

Every Entity Kind has a list of connectors. The get CLI (and Web Server UI) automatically invoke each of these connectors to “augment” an Entity. (They are called in the declared order, and each “stage” can “add on” to the previous.)

URI Templates

Models can contain {...} in the uri_template of link and the paths of related.

Those are URI Template (from RFC 6570). The available variables are:

• path.xyz where xyz is one of the paths of the EntityKind

The templates are evaluated last, and not set if another Connector has already set a value for the respect link or related.

The demo on the Get CLI documentation illustrates this connector.

File System Repository

This connector complements entities by merging them with data from a file.

This is useful e.g. for testing, but also in production for “fixed” entities.

For example, this model-fs.yaml:

kinds:
  - id: { ns: demo, entity: book_kind, paths: [isbn] }
    link:
      google:
        label: Google Book Search
        uriTemplate: "https://www.google.com/search?tbm=bks&q=isbn:{path.isbn}"
    data:
      authors:
        label: Names of the authors of this book.
        type_url: demo.enola.dev/dev.enola.demo.Something
    connectors:
      - fs:
          path: docs/use/connector/
          # TODO https://github.com/enola-dev/enola/issues/238
          # protos:
          #   - ../../connectors/demo/src/main/java/dev/enola/demo/demo_data.proto
          format: FORMAT_YAML

with this demo.book_kind/0-13-140731-7.yaml:

link:
  google: http://www.vorburger.ch/corejdo/

  # TODO https://github.com/enola-dev/enola/issues/238
  # data:
  #   authors: {'@type': demo.enola.dev/dev.enola.demo.Something, text: 'hello, world', names: ... }
  #     - Sameer Tyagi
  #     - Michael Vorburger
  #     - Keiron McCannon
  #     - Heiko Bobzin

will cause:

$ ./enola get --model file:docs/use/connector/model-fs.yaml demo.book_kind/0-13-140731-7
id:
  ns: demo
  entity: book_kind
  paths: [0-13-140731-7]
ts: 2024-07-27T00:59:36.402846593Z
link: {google: 'http://www.vorburger.ch/corejdo/'}

The File System Repository Connector does not yet support the Any fields in data.

gRPC

This connector complements entities by invoking a remote gRPC microservice which implements the ConnectorService API. You can (and should) implement this yourself, but just for illustration, let’s use a trivial demo one. For example, this model-grpc.yaml:

kinds:
  - id: { ns: demo, entity: book_kind, paths: [isbn] }
    link:
      link1:
        label: Link without uriTemplate, will be set by connector
    data:
      data1:
        label: "Details"
        type_url: "demo.enola.dev/dev.enola.demo.Something"
    connectors:
      - grpc: localhost:9090

we can see it in action by running demo-grpc.bash:

$ # ./demo-grpc.bash

In addition to returning entities themselves, gRPC Connectors also provide the Protocol Buffer schemas (as FileDescriptorProto) for the Any fields in data of the EntityKind they handle.

Error

This connector always triggers an error, and is only intended for testing; e.g. this model-error.yaml:

kinds:
  - id: { ns: demo, entity: book_kind, paths: [isbn] }
    connectors:
      - error: "Fail fast, then get up even faster, to continue running!"

will cause:

$ ./enola get --model file:docs/use/connector/model-error.yaml demo.book_kind/0-13-140731-7
Internal Problem occured, add -vvv flags for technical details: UNKNOWN: Application error processing RPC
caused by: demo.book_kind/0-13-140731-7
caused by: Fail fast, then get up even faster, to continue running!

Java

This connector complements entities by invoking a Java class “in-process”. To illustrate, we could e.g. directly use the internal implementation of the error connector like this:

kinds:
  - id: { ns: demo, entity: book_kind, paths: [isbn] }
    connectors:
      - java_class: dev.enola.core.aspects.ErrorTestAspect

which will cause:

$ ./enola get --model file:docs/use/connector/model-java.yaml demo.book_kind/0-13-140731-7
Internal Problem occured, add -vvv flags for technical details: UNKNOWN: Application error processing RPC
caused by: demo.book_kind/0-13-140731-7
caused by: Failure is just a stepping stone to greatness.

Using this connector with your own code requires extending Enola by linking it as a Java library.

The recommended approach for integration is to write remote connectors instead.

CLI

TBD We may add a generic CLI Connector in the future, which could exec-ute a local command to complete an Entity. (It would be customizable with templates for command arguments, and the choice of JSON/YAML/Text- or Binary Proto on STDIN, and expected output format of the completed Entity on STDOUT.)

Timestamp

The ts of an Entity is automatically set to the current time by a built-in connector (which does not need to be declared) - unless another Connector has already set it, i.e. from data read from some “back-end”. (E.g. the File System Repository does this based on the entity file’s last modified attribute.)