Swift Haystack

An implementation of Project Haystack in Swift.

Getting Started

To use this package, add it to your Package.swift dependencies:

dependencies:[.package(url:"https://github.com/NeedleInAJayStack/swift-haystack.git", from:"0.0.0"),],targets:[.target(
name:"MyTarget",
dependencies:[.product(name:"Haystack",package:"swift-haystack"),]),]

You can then import and use the different libraries:

import Haystack
func testGrid()throws->Grid{returntryZincReader(""" ver:"3.0" foo:"bar" dis dis:"Equip Name", equip, siteRef, installed"RTU-1", M, @153c-699a HQ, 2005-06-01"RTU-2", M, @153c-699b Library, 1997-07-12""").readGrid()}

See below for available libraries and descriptions.

Available Packages

Haystack

This contains the Haystack type-system primitives and utilities to interact with them.

HaystackClient

This defines the main functionality of Haystack API clients. It should not be imported directly; its assets are imported automatically by HaystackClientDarwin or HaystackClientNIO.

Once you create a client, you can use it to make requests:

func yesterdaysValues()asyncthrows->Grid{letclient=...
// Open and authenticate. This must be called before requests can be made
tryawait client.open()
// Request the historical values for @28e7fb7d-e20316e0
letgrid=tryawait client.hisRead(id:Ref("28e7fb7d-e20316e0"), range:.yesterday)
// Close the client session and log out
tryawait client.close()return grid
}

HaystackServer

This defines the standard functionality and data processing of Haystack API servers, based on generic backing data stores. In most cases, Haystack servers should use the HaystackServer class and customize storage behavior by implementing the RecordStore, HistoryStore, and WatchStore protocols.

structInfluxHistoryStore:HistoryStore{
// Define storage behavior here
...}letserver=HaystackServer(
historyStore:InfluxHistoryStore(),...)

Available Traits

ClientDarwin

A Darwin-only client driver for the Haystack HTTP API that requires minimal dependencies. Use this if you are only deploying to MacOS, iOS, etc and want to reduce dependencies.

Here's an example of how to use it:

import HaystackClient
func client()throws->Client{returntryClient(
baseUrl:"http://mydomain.com/api/",
username:"username",
password:"password")}

ClientNIO

A cross-platform client driver for the Haystack HTTP API that has larger dependency requirements. Use this if you are only deploying to Linux or if you are deploying to Darwin platforms and are willing to accept more dependencies.

Here's an example of how to use it:

import HaystackClient
func client()throws->Client{lethttpClient=HTTPClient(eventLoopGroupProvider:.createNew)returntryClient(
baseUrl:"http://mydomain.com/api/",
username:"username",
password:"password",
httpClient: httpClient
)}

ServerVapor

A server for the Haystack HTTP API that uses Vapor. It's separated from the HaystackServer package so that clients may use alternative server technologies if they choose, including Hummingbird or NIO directly.

It exposes a HaystackRouteCollection that can be registered on a Vapor application:

letapp=Application()try app.register(collection:HaystackRouteCollection(delegate:...))

The delegate is a protocol that can be implemented however the user sees fit, although the standard Haystack implementation is defined in HaystackServer.

Contributing

Integration tests

To run the integration tests, run a local Haxall server:

docker run -e 'SU_PASS=su' -p '8080:8080' needleinajaystack/haxall:latest

License

This package is licensed under the Academic Free License 3.0 for maximum compatibility with Project Haystack itself.