1 6456042b 2022-01-06 o package icinga provides a client to the Icinga2 HTTP API.
  2 6456042b 2022-01-06 o 
  3 87154adc 2022-02-04 o [![builds.sr.ht status](https://builds.sr.ht/~otl/icinga.svg)](https://builds.sr.ht/~otl/icinga?)
  4 87154adc 2022-02-04 o 
  5 6456042b 2022-01-06 o [![godocs.io](http://godocs.io/olowe.co/icinga?status.svg)](http://godocs.io/olowe.co/icinga)
  6 6456042b 2022-01-06 o 
  7 fb8a219e 2022-10-22 o Send patches, questions or a friendly "hello" to the mailing list: [~otl/public-inbox@lists.sr.ht](mailto:~otl/public-inbox@lists.sr.ht)
  8 2ad5e459 2022-01-12 o Or, read [the archives][list].
  9 26fb88e9 2022-01-12 o 
 10 6456042b 2022-01-06 o ## Quick Start
 11 6456042b 2022-01-06 o 
 12 7aa5b055 2022-01-13 o See the [package overview godoc][godocs] for getting started examples.
 13 6456042b 2022-01-06 o 
 14 6456042b 2022-01-06 o [godocs]: https://godocs.io/olowe.co/icinga
 15 6456042b 2022-01-06 o 
 16 26fb88e9 2022-01-12 o ## Development
 17 26fb88e9 2022-01-12 o 
 18 26fb88e9 2022-01-12 o Some code is automatically generated. Ensure it's up-to-date before starting work:
 19 26fb88e9 2022-01-12 o 
 20 26fb88e9 2022-01-12 o 	go generate
 21 26fb88e9 2022-01-12 o 
 22 2ad5e459 2022-01-12 o Make some changes, then run the tests:
 23 26fb88e9 2022-01-12 o 
 24 26fb88e9 2022-01-12 o 	go test
 25 26fb88e9 2022-01-12 o 
 26 fb8a219e 2022-10-22 o Please send any patches to the [mailing list][list]:
 27 26fb88e9 2022-01-12 o 
 28 fb8a219e 2022-10-22 o 	git send-email --to="~otl/public-inbox@lists.sr.ht" HEAD^
 29 26fb88e9 2022-01-12 o 
 30 7aa5b055 2022-01-13 o For those unfamiliar with this workflow, see [git-send-email.io][sendemail].
 31 2ad5e459 2022-01-12 o 
 32 fb8a219e 2022-10-22 o [list]: https://lists.sr.ht/~otl/public-inbox
 33 7aa5b055 2022-01-13 o [sendemail]: https://git-send-email.io
 34 7aa5b055 2022-01-13 o 
 35 2ad5e459 2022-01-12 o ### Tests
 36 2ad5e459 2022-01-12 o 
 37 b717ce9b 2022-02-04 o Some tests use a fake, in-process Icinga server. Not all features of
 38 b717ce9b 2022-02-04 o the API are implemented, but on any unsupported request it should
 39 b717ce9b 2022-02-04 o report an error. The fake server uses an in-memory map to store
 40 b717ce9b 2022-02-04 o Icinga2 objects, which maps object's path in the API request (e.g.
 41 b717ce9b 2022-02-04 o "objects/hosts/text.example.com") to the object's attributes (e.g.
 42 b717ce9b 2022-02-04 o `check_command` and `display_name`).
 43 b717ce9b 2022-02-04 o 
 44 26fb88e9 2022-01-12 o Some tests dial an instance of Icinga2 running on the loopback address
 45 b717ce9b 2022-02-04 o and the standard Icinga2 port 5665 (`::1:5665`). If this fails, those
 46 b717ce9b 2022-02-04 o tests are skipped. To run these tests, create the following API user:
 47 26fb88e9 2022-01-12 o 
 48 b717ce9b 2022-02-04 o 	object ApiUser "icinga" {
 49 b717ce9b 2022-02-04 o 		password = name
 50 26fb88e9 2022-01-12 o 		permissions = [ "*" ]
 51 26fb88e9 2022-01-12 o 	}
 52 26fb88e9 2022-01-12 o 
 53 b717ce9b 2022-02-04 o Getting data from the loopback interface to an Icinga server is left
 54 b717ce9b 2022-02-04 o as an exercise to the reader!
 55 26fb88e9 2022-01-12 o 
 56 26fb88e9 2022-01-12 o Personally, I run an Alpine Linux virtual machine using qemu. You
 57 26fb88e9 2022-01-12 o could also use the [official Icinga2 container image][image].
 58 26fb88e9 2022-01-12 o 
 59 26fb88e9 2022-01-12 o [image]: https://hub.docker.com/r/icinga/icinga2
 60 26fb88e9 2022-01-12 o 
 61 26fb88e9 2022-01-12 o ### Code generation
 62 26fb88e9 2022-01-12 o 
 63 26fb88e9 2022-01-12 o Source code for the basic lookup, create and delete operations of some
 64 26fb88e9 2022-01-12 o Icinga2 object types, such as Host and Service, are generated
 65 26fb88e9 2022-01-12 o automatically.
 66 26fb88e9 2022-01-12 o 
 67 dd1562c0 2022-01-18 o To generate the code, ensure the following tools are available:
 68 dd1562c0 2022-01-18 o 
 69 dd1562c0 2022-01-18 o * POSIX shell (/bin/sh)
 70 dd1562c0 2022-01-18 o * awk
 71 dd1562c0 2022-01-18 o * gofmt
 72 dd1562c0 2022-01-18 o 
 73 26fb88e9 2022-01-12 o The shell script crud.sh writes Go source code by reading a template
 74 26fb88e9 2022-01-12 o file and doing some text substitution. It loops through object types,
 75 26fb88e9 2022-01-12 o piping the template file crud.skel into the awk script crud.awk for
 76 26fb88e9 2022-01-12 o each.
 77 26fb88e9 2022-01-12 o 
 78 26fb88e9 2022-01-12 o crud.sh writes code to the standard output by default:
 79 26fb88e9 2022-01-12 o 
 80 26fb88e9 2022-01-12 o 	./crud.sh
 81 26fb88e9 2022-01-12 o 
 82 26fb88e9 2022-01-12 o If the flag `-o` is set, code will be written to the file
 83 26fb88e9 2022-01-12 o specified instead of to standard output:
 84 26fb88e9 2022-01-12 o 
 85 26fb88e9 2022-01-12 o 	./crud.sh -o crud.go
 86 26fb88e9 2022-01-12 o 
 87 26fb88e9 2022-01-12 o Code generation is used because the functions are trivial and call the exact
 88 26fb88e9 2022-01-12 o same underlying methods on Client anyway. The only thing that differs is the type.
 89 26fb88e9 2022-01-12 o Perhaps when Go gets type parameters then this will go away?
 90 26fb88e9 2022-01-12 o 
 91 6456042b 2022-01-06 o ## Why Another Package?
 92 6456042b 2022-01-06 o 
 93 6456042b 2022-01-06 o The [icinga2 terraform provider][tf] uses the package [github.com/lrsmith/go-icinga2-api/iapi][lrsmith].
 94 6456042b 2022-01-06 o As I read the source code I felt I wasn't reading idiomatic Go as detailed in documents like [Effective Go][effectivego].
 95 6456042b 2022-01-06 o Other properties of `iapi` felt unusual to me:
 96 6456042b 2022-01-06 o 
 97 6456042b 2022-01-06 o * The client to the API has the  confusing name `server`.
 98 6456042b 2022-01-06 o * Every HTTP request creates a new http.Client.
 99 6456042b 2022-01-06 o * Types have superfluous names like `HostStruct` instead of just `Host`.
100 6456042b 2022-01-06 o * Every response body from the API is decoded from JSON into one data strucutre, marshalled into JSON again, then unmarshalled back into another.
101 6456042b 2022-01-06 o * Every error returned from a function has a new name, rather than reusing the idiomatic name `err`.
102 6456042b 2022-01-06 o 
103 6456042b 2022-01-06 o If I was being paid, I'd create a fork and contribute patches upstream to carefully avoid breaking functionality of existing users of `iapi`.
104 6456042b 2022-01-06 o 
105 6456042b 2022-01-06 o But I'm not being paid ;)
106 6456042b 2022-01-06 o 
107 6456042b 2022-01-06 o [effectivego]: https://go.dev/doc/effective_go
108 6456042b 2022-01-06 o [tf]: https://registry.terraform.io/providers/Icinga/icinga2/latest
109 6456042b 2022-01-06 o [lrsmith]: https://godocs.io/github.com/lrsmith/go-icinga2-api/iapi