Hackage :: [Package]

mellon-web: A REST web service for Mellon controllers

[ bsd3, library, web ] [ Propose Tags ]

The mellon-web package wraps a mellon-core controller in a REST web service, making it possible to control physical access devices from an HTTP client. The package includes both a WAI application server, and native Haskell client bindings for the service.

Like the mellon-core controller interface, the mellon-web REST API is quite simple. There are only 3 methods:

  • GET /time returns the system time on the server. This is made available for diagnostic purposes, primarily to ensure the server has an accurate clock.

  • GET /state returns the controller's current state (either Locked or Unlocked date where date is the UTC time at which the controller will automatically lock again).

  • PUT /state sets the controller's current state. Use this method to lock and unlock the controller.

For detailed documentation, the server includes a self-documenting Swagger spec.

Note that the mellon-web server does not provide an authentication mechanism! You should proxy it behind a secure, authenticating HTTPS server such as Nginx.

[Skip to Readme]

Flags

Manual Flags

NameDescriptionDefault
client-unlock-example

Build the unlock client example

Enabled
enable-timing-sensitive-tests

Enable tests that are timing-sensitive (may fail on loaded machines like CI servers)

Disabled
gpio-example

Build the GPIO server example

Enabled
mock-example

Build the mock server example

Enabled
test-doctests

Build doctests

Enabled
test-hlint

Build hlint test

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.7.0.1, 0.7.0.3, 0.7.1.0, 0.7.1.1, 0.8.0.2, 0.8.0.3, 0.8.0.4, 0.8.0.5, 0.8.0.6, 0.8.0.7
Change log changelog.md
Dependencies aeson (>=0.11 && <1.3), aeson-pretty (>=0.8 && <0.9), base (>=4.8 && <5), bytestring (>=0.10 && <0.11), exceptions (>=0.8.0 && <1), fail (>=4.9 && <4.10), hpio (>=0.8 && <1), http-client (>=0.4 && <0.6), http-client-tls (>=0.3 && <0.4), http-types (>=0.9 && <0.13), lens (>=4 && <5), lucid (>=2.9 && <2.10), mellon-core, mellon-gpio, mellon-web, mtl (>=2.1.3 && <2.3), network, optparse-applicative (>=0.11.0 && <0.15), protolude (>=0.2 && <0.3), semigroups (>=0.18 && <0.19), servant (>=0.13 && <0.14), servant-client (>=0.13 && <0.14), servant-client-core (>=0.13 && <0.14), servant-docs (>=0.10 && <0.12), servant-lucid (>=0.7 && <0.9), servant-server (>=0.13 && <0.14), servant-swagger (>=1.1 && <1.2), servant-swagger-ui (>=0.2 && <0.3), swagger2 (>=2.1 && <2.3), text (>=1.2 && <1.3), time (>=1.5 && <2), transformers (>=0.4.2 && <0.6), wai (>=3.2 && <3.3), warp (>=3.2 && <3.3) [details]
License BSD-3-Clause
Copyright Copyright (c) 2018, Quixoftic, LLC
Author Drew Hess <dhess-src@quixoftic.com>
Maintainer Drew Hess <dhess-src@quixoftic.com>
Category Web
Home page https://github.com/quixoftic/mellon#readme
Bug tracker https://github.com/quixoftic/mellon/issues
Source repo head: git clone https://github.com/quixoftic/mellon
Uploaded by dhess at 2018-04-03T23:12:13Z
Distributions NixOS:0.8.0.7
Executables mock-mellon-server, mellon-schedule-unlock, gpio-mellon-server
Downloads 5328 total (24 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2018-04-14 [all 1 reports]

Readme for mellon-web-0.8.0.7

[back to package description]

mellon-web

The mellon-web package wraps a mellon-core controller in a REST web service, making it possible to control physical access devices from an HTTP client. The package includes both a WAI application server, and native Haskell client bindings for the service.

Like the mellon-core controller interface, the mellon-web REST API is quite simple. There are only 3 methods:

  • GET /time returns the system time on the server. This is made available for diagnostic purposes, primarily to ensure the server has an accurate clock.

  • GET /state returns the controller's current state (either Locked or Unlocked date where date is the UTC time at which the controller will automatically lock again).

  • PUT /state sets the controller's current state. Use this method to lock and unlock the controller.

For detailed documentation, the server includes a self-documenting Swagger spec.

Note that the mellon-web server does not provide an authentication mechanism! You should proxy it behind a secure, authenticating HTTPS server such as Nginx.

Example servers

"Mock" server

An extremely simple example server (with on-line documentation support) is provided in the examples directory. You can run it with cabal run mock-mellon-server. The server is will run on the localhost loopback interface on port 8081.

This particular example server uses a "mock lock" device which only internally logs lock and unlock events without depending on any actual hardware, so it will run anywhere.

GPIO server

Another included example server uses the mellon-gpio package to drive a simple physical access device via a GPIO pin. This server must be run on a Linux host with GPIO hardware, e.g., a Raspberry Pi running Linux.

This server takes a GPIO pin number and a local port number, then starts a mellon-web server on all local interfaces on the specified port. When the server receives an unlock request, it will drive a high signal on the specified GPIO pin. When the unlock expires, or when the server receives a lock request, it will drive a low signal on the specified GPIO pin.

To use this server, simply connect a properly-designed physical access device (e.g., an electric strike driven by a relay circuit such as the one shown here) to an available GPIO pin on the host device, then run the server with the specified GPIO pin number and port. For example, to run the server on port 7533 using GPIO pin 65:

cabal run gpio-mellon-server -- sysfs --port 7533 65

The sysfs command tells the server to use the Linux sysfs GPIO interpreter. (Currently, this is the only supported GPIO platform.)

NOTE: the REST service provided by gpio-mellon-server offers no security/authentication for your access control device! You should always run it (or any mellon-web server) behind a secure proxy web service or equivalent HTTP(S)-based authentication mechanism.

Travis CI build status