haystack-client 0.1.2

Client library and CLI tool for interacting with haystack servers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

# Haystack Client

Rust implementation of an async haystack client library and CLI tool and REPL.

## Implemented Ops

- [x] About
- [x] Close
- [x] Defs
  - [x] filter
  - [x] limit
- [x] Libs
  - [x] filter
  - [x] limit
- [x] Ops
  - [x] filter
  - [x] limit
- [x] Filetypes
  - [x] filter
  - [x] limit
- [x] Read
  - [x] By filter
  - [x] By id
- [x] Nav
- [x] WatchSub
- [x] WatchUnsub
- [x] WatchPoll
- [ ] PointWrite
- [x] hisRead
  - [x] Single
  - [x] Batch
- [x] hisWrite (Must be valid zinc str)
  - [x] Single
  - [x] Batch
- [ ] Invoke Action

## Example CLI uses

```console
# Reuse haystack bearer token

( # () Opens a sub-shell
  export HAYSTACK_AUTH_CONFIG=`hs default auth`;
  
  # Destination does not need to be included if the environment variable
  # HAYSTACK_AUTH_CONFIG is set.
  
  # I also set up my .bashrc to use the alias "hs" instead of the full name.
  # Stick with `haystack-client` if you haven't configured your .bashrc this way
  hs read --filter "point" --limit=1

  # Example below of correct character escaping in bash shell when passing
  # filters enclosed by either single or double quotes.
  hs read --filter 'point and unit==\"kWh\" and equipRef->siteRef'
  hs read --filter "point and unit==\\\"kWh\\\" and equipRef->siteRef"
)

# Read–eval–print loop (REPL) You will see the prompt "hs〉"

# To learn about the $DEST argument, see the configuration section below.

haystack-client $DEST repl
hs〉about

# About

haystack-client $DEST about

# Read by filter

haystack-client $DEST read --filter "point and unit==\"kWh\" and equipRef->siteRef"

# Read by ids

haystack-client $DEST read --ids @p:demo:r:2f70054a-87f6d1de @p:demo:r:2f70054a-314342cd

# His Read (single)

haystack-client $DEST hisRead yesterday @p:demo:r:2f70054a-87f6d1de

# His Read (batch, could use the optional --timezone argument)

haystack-client $DEST hisRead yesterday @p:demo:r:2f70054a-87f6d1de @p:demo:r:2f70054a-314342cd

# WatchSub

## Can create watches with or without an id list

haystack-client $DEST watchSub -c "test" @p:demo:r:2f70054a-51d71f8e

## Subscribing points to a watch

haystack-client $DEST watchSub -s "w-2f8e0d48-64f17e75" @p:demo:r:2f70054a-51d71f8e @p:demo:r:2f70054a-69f26216

# Unsubscribing and closing a watch

haystack-client $DEST watchUnsub --close w-2f8e1d8b-8efac249
haystack-client $DEST watchUnsub @p:demo:r:2f70054a-51d71f8e

# Watch Poll (with or without --refresh)

haystack-client $DEST watchPoll w-2f8e2739-3c4b3bde --refresh

# Defs

haystack-client $DEST defs "name==\\\"testJob\\\"" --limit 1
```

## TODO

* Implement remaining Haystack OPs
* Provide options that allow the user to control the structure and format of returned grid. i.e. when creating new watches, allow the user to return the `watchId` only.
* Provide option for watches to be reopened automatically if an error grid is returned on watch OPs.
* Treat error grids as errors
* Provide some more advanced tooling to suport `hisWrite`
    - Support to map data from CSV to native haystack types
    - Support for different filetypes
        * CSV, ZINC, JSON, Trio
    - Support methods to map to point rec IDs on the server
    - Embed scripting language, i.e. lua or awk?
* Use an alternative library for SCRAM authentication