hive-io-rest-example

An example REST module to help describe implementation details when leveraging the Hive^io framework.

Overview
- Endpoints
- Source Code
Getting Started

Overview

This example contains a single resource to handle CRUD functionality of a generic Content object in a Restful implementation. It is a contrived but fairly robust example to illustrate different ways to use Actors in the Hive^io framework.

Endpoints

Once you get the app running using the setup instructions below, you can use the application from the following endpoint(s):

http://localhost/contents (GET, POST)
- POST API JSON Schema
```
{
  "text": "something"
}
```
http://localhost/contents/<id> (GET, PATCH, DELETE)
- PATCH API JSON Schema
```
{
  "text": "something different"
}
```
- DELETE

NOTE: Network data models follow the Flux Standard Action specification for network transport. type and payload are derived from the routes and data sent respectively in this example.

Source Code

Getting Started

This is a straight forward CRUD example of a Content Entity that contains text, a couple Boolean flags, and a count of how many views it has. It stores these Contents in MongoDB. It leverages Hive^io's built-in telemetry solution with OpenTelemetry. Here's how to use it.

NOTE: This does not include robust error handling, authentication, and other strategies to keep the example straight forward.

Prerequisites

To use, you'll need:

Required
- Docker
- Docker Compose

Installing

To start using:

Create the following files:

Dockerfile

FROM fnalabs/hive-base-js:latest
RUN npm install --production --no-optional hive-io-rest-example

docker-compose.yml

version: '3.5'
services:
  hive-base-js:
    build: .
    image: hive-base-js:production
    container_name: hive-base-js
    environment:
      ACTOR: ContentActor
      ACTOR_LIB: hive-io-rest-example
      ACTOR_URLS: "/contents,/contents/:id"
      CLUSTER_SIZE: 1
      HTTP_VERSION: 1
      SECURE: "false"
      TELEMETRY: "true"
      TELEMETRY_PLUGINS: '{"mongodb":{"enabled":true,"path":"@opentelemetry/plugin-mongodb"},"mongoose":{"enabled":true,"path":"@wdalmut/opentelemetry-plugin-mongoose"}}'
      TELEMETRY_SERVICE_NAME: content
      TELEMETRY_URL_METRICS: "http://collector:55681/v1/metrics"
      TELEMETRY_URL_TRACES: "http://collector:55681/v1/trace"
      MONGO_URL: "mongodb://mongo:27017/contents"
    depends_on:
      - collector
      - mongo
    ports:
      - 80:3000
    networks:
      - hive-io
  mongo:
    image: mongo:4.4.3
    container_name: mongo
    networks:
      - hive-io
    restart: on-failure

  # telemetry
  # TODO: you will need to define your own config for this example
  #       https://github.com/fnalabs/hive-io/blob/master/dev/collector/collector-config.yml
  collector:
    image: otel/opentelemetry-collector:0.18.0
    container_name: collector
    command: ["--config=/conf/collector-config.yml", "--log-level=ERROR"]
    depends_on:
      - zipkin
    volumes:
      - ./collector-config.yml:/conf/collector-config.yml
    networks:
      - hive-io
    restart: on-failure
  zipkin:
    image: openzipkin/zipkin:2.23.2
    container_name: zipkin
    ports:
      - 9411:9411
    networks:
      - hive-io
    restart: on-failure

# networking
networks:
  hive-io:
    driver: bridge

Run the following commands:
```
docker-compose up
```

Environment Variables

The table below contains a reference to the custom environment variables used in the example. Standard environment variables are documented for the following microservice containers:

hive-base-js

Name	Type	Default	Description
MONGO_URL	String	'mongodb://mongo:27017/contents'	url to connect to MongoDB instance