@actyx-contrib/actyx-http-connector
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published

    Actyx-HTTP-Connector

    Need a connector to talk to an Actyx swarm from external applications via HTTP?

    Actyx-HTTP-Connector allows you to build one in a few minutes while keeping the embedded HTTP server fully customizable.

    Features

    The HTTP connector allows you to interact with a swarm of Actyx nodes by providing an HTTP interface to systems not running Actyx. You can use it to ...

    • ... inject data from other systems that will be injected into the Actyx swarm in the form of events (think webhooks)
    • ... query Fish state from non-Actyx applications to show data from Actyx in other apps (e.g. legacy web apps)
    • ... get updates from the Actyx swarm via WebSockets

    The connector provides hooks you can use to influence the behavior of the underlying HTTP server/web framework, Express. You can use these hooks to ...

    • ... add middleware like encryption, body-parsers or authentication
    • ... add static file resources
    • ... provide additional routes or catch-all route handlers

    Additionally, you can query information like your local source ID, the [Pond](https://developer.actyx.com/docs/pond/introduction/ state, and whether the node running the HTTP connector is in sync with the swarm to be able to deal with error conditions better.

    ⚖️ Trade-Offs

    Note, however, that web apps running on the HTTP connector do not provide the same level of resilience that Actyx apps do.

    This is typically not an issue when interfacing with external systems (top floor, back office). But you should probably not use it to build applications that run on the shop floor and need to be highly available and resilient.

    📦 Installation

    Actyx-HTTP-Connector is available as an npm package.

    npm install @actyx-contrib/actyx-http-connector

    📖 Documentation

    The complete API documentation and related examples are available at https://actyx-contrib.github.io/actyx-HTTP-Connector

    Detailed Examples

    You can find sample applications on GitHub.

    The simple example exposes the possibility to query Fish state and emit events to the Pond directly. The advanced example adds WebSocket communication, uses event emitters and adds authentication. Both projects come with a simple React based app. Note that these apps do not directly talk to an Actyx node but interface through the HTTP connector.

    Make sure you have an Axtyx node running on your machine before starting the examples. You can get the binaries from our download site.

    You can start the examples using npm i && npm run example:simple or npm i && npm run example:advanced, respectively. The apps are accessible at http://localhost:1234. If that port is already allocated, the build picks another one at random. Check the build's console output to be sure.

    🤓 Quick start

    To have access to your Actyx Fish definitions and the Pond, it is best to create your HTTP server as part of an (probably already existing) axp project.

    $ cd <my project folder>
    $ axp init # only if you do not already have an Actyx project in place
    $ axp add node --appName http-api
    $ npm install @actyx-contrib/actyx-http-connector --save

    🔌 Add httpConnector

    In your http-api app's index.ts, import the HTTP connector, then use httpConnector() to create a server instance as shown below. For further details, please refer to the docs and the examples.

    import { httpConnector, registryEntry } from '@actyx-contrib/actyx-http-connector'
    import { Pond } from '@actyx/pond'
    
    Pond.default().then(pond => {
      httpConnector({
        // The pond instance is required for the HTTP-Connector
        pond,
        // Allows the user of the HTTP-Connector to emit events directly into actyx.
        // It is not recommended to use this feature.
        // Please use `eventEmitters` or at least add an authentication with `preSetup`
        allowEmit: true,
        // Propagate which fish you like to access from external programs.
        // The fish will be published over the HTTP get request or can be observed with the websocket
        registry: { someFish: registryEntry(SomeFish.of) },
      })

    🤓 Examples

    Minimal example

    The minimal example simply allows you to emit events directly into actyx using an HTTP API.

    import { httpConnector, registryEntry } from '../../src'
    import { Pond } from '@actyx/pond'
    // Api Server
    Pond.default().then(pond => {
      httpConnector({
        // The pond instance is required for the HTTP-Connector
        pond,
        // Allows the user of the HTTP-Connector to emit events directly into actyx.
        // It is not recommended to use this feature.
        // Please use `eventEmitters` or at least add an authentication with `preSetup`
        allowEmit: true,
        // Propagate which fish you like to access from external programs.
        // The fish will be published over the HTTP get request or can be observed with the websocket
        registry: { someFish: registryEntry(SomeFish.of) },
      })
    })

    Complete example

    The complete example shows also shows how to hook in middlewares and the usage of event emitters.

    import { httpConnector, registryEntry } from '../../src'
    import { Pond } from '@actyx/pond'
    // Api Server
    Pond.default().then(pond => {
      httpConnector({
        // The pond instance is required for the HTTP-Connector
        pond,
        // Propagate which fish you like to access from external programs.
        // The fish will be published over the HTTP get request or can be observed with the websocket
        registry: {
          someFish: registryEntry(SomeFish.of),
        },
        // Add event emitters.
        // This methode is much safer than the `allowEmit: true`, you are in control which event
        // are emitted and you can verify the event with TypeScript or io-TS
        eventEmitters: {
          startSomeFish: async (pond, _payload) => {
            await SomeFish.emitStart(pond)
            return EmitResult.reply(204)
          },
        },
        // Add the authentication layer before the routes are created.
        // this hook is added after urlencoded, json, cors, you could add XML parser,
        // cookie parser and other middleware you like
        preSetup: app => {
          app.use(xmlparser())
          // add Authentication
        },
        // Add a handler after the routes are added to express.
        // This could be used for a default "404 not-Found" page or a redirect to your documentation
        postSetup: app => {
          app.use((_req, res, _next) => res.redirect('https://community.actyx.com'))
        },
      })
    })

    Install

    npm i @actyx-contrib/actyx-http-connector

    DownloadsWeekly Downloads

    20

    Version

    1.0.2

    License

    Apache-2.0

    Unpacked Size

    55.5 kB

    Total Files

    11

    Last publish

    Collaborators

    • alex(actyx)
    • ostollmann
    • roland.kuhn