lang: core: embedded: Add standalone provisioning tool

This commit adds the ability to build a standalone provisioning tool.
This is the first useful public mcl code base as well. It is not
perfect, but does serve as a rough starting point to show what is
possible. In the future as the language and the engine evolve, this will
likely get more elegant, and also grow new features.

To build this, run `make clean && GOTAGS='embedded_provisioner' make`.
To run this, run `mgmt provisioner`.

.ackrc

@@ -1,2 +1,6 @@
 --ignore-dir=old/
 --ignore-dir=tmp/
+--ignore-dir=vendor/
+--ignore-dir=releases/
+--ignore-dir=rpmbuild/
+--type-set=mcl:ext:mcl

.dockerignore

@@ -0,0 +1 @@
+docker

.editorconfig

@@ -0,0 +1,28 @@
+; This file is for unifying the coding style for different editors and IDEs.
+; Plugins are available for notepad++, emacs, vim, gedit,
+; textmate, visual studio, and more.
+;
+; See http://editorconfig.org for details.
+
+# Top-most EditorConfig file.
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.sh]
+indent_style = tab
+
+[*.go]
+indent_style = tab
+
+[Makefile]
+indent_style = tab
+
+[*.mcl]
+indent_style = tab
+
+[*.txtar]
+indent_style = tab

.github/FUNDING.yml

@@ -0,0 +1,5 @@
+# You can add one username per supported platform and one custom link.
+custom: "https://paypal.me/purpleidea"
+github: purpleidea
+liberapay: purpleidea
+patreon: purpleidea

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,9 @@
+## Versions:
+
+* mgmt version (eg: `mgmt --version`):
+
+* operating system/distribution (eg: `uname -a`):
+
+* golang version (eg: `go version`):
+
+## Description:

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,47 @@
+## Tips:
+
+* please read the style guide before submitting your patch:
+[docs/style-guide.md](../docs/style-guide.md)
+
+* commit message titles must be in the form:
+
+```topic: Capitalized message with no trailing period```
+
+or:
+
+```topic, topic2: Capitalized message with no trailing period```
+
+* golang code must be formatted according to the standard, please run:
+
+```
+make gofmt		# formats the entire project correctly
+```
+
+or format a single golang file correctly:
+
+```
+gofmt -w yourcode.go
+```
+
+* please rebase your patch against current git master:
+
+```
+git checkout master
+git pull origin master
+git checkout your-feature
+git rebase master
+git push your-remote your-feature
+hub pull-request	# or submit with the github web ui
+```
+
+* after a patch review, please ping @purpleidea so we know to re-review:
+
+```
+# make changes based on reviews...
+git add -p		# add new changes
+git commit --amend	# combine with existing commit
+git push your-remote your-feature -f
+# now ping @purpleidea in the github PR since it doesn't notify us automatically
+```
+
+## Thanks for contributing to mgmt and welcome to the team!

.github/settings.yml

@@ -0,0 +1,98 @@
+# These settings are synced to GitHub by https://probot.github.io/apps/settings/
+
+repository:
+  # See https://developer.github.com/v3/repos/#edit for all available settings.
+
+  # The name of the repository. Changing this will rename the repository
+  name: mgmt
+
+  # A short description of the repository that will show up on GitHub
+  description: Next generation distributed, event-driven, parallel config management!
+
+  # A URL with more information about the repository
+  homepage: https://purpleidea.com/tags/mgmtconfig/
+
+  # A comma-separated list of topics to set on the repository
+  topics: golang, go, configuration-management, config-management, devops, etcd, distributed-systems, graph-theory, choreography
+
+  # Either `true` to make the repository private, or `false` to make it public.
+  private: false
+
+  # Either `true` to enable issues for this repository, `false` to disable them.
+  has_issues: true
+
+  # Either `true` to enable projects for this repository, or `false` to disable them.
+  # If projects are disabled for the organization, passing `true` will cause an API error.
+  has_projects: false
+
+  # Either `true` to enable the wiki for this repository, `false` to disable it.
+  has_wiki: false
+
+  # Either `true` to enable downloads for this repository, `false` to disable them.
+  has_downloads: true
+
+  # Updates the default branch for this repository.
+  default_branch: master
+
+  # Either `true` to allow squash-merging pull requests, or `false` to prevent
+  # squash-merging.
+  allow_squash_merge: false
+
+  # Either `true` to allow merging pull requests with a merge commit, or `false`
+  # to prevent merging pull requests with merge commits.
+  allow_merge_commit: false
+
+  # Either `true` to allow rebase-merging pull requests, or `false` to prevent
+  # rebase-merging.
+  allow_rebase_merge: true
+
+# Labels: define labels for Issues and Pull Requests (in alphabetical order)
+labels:
+  - name: bug
+    color: fc2929
+  - name: confirmed
+    color: d93f0b
+  - name: design
+    color: 5319e7
+  - name: duplicate
+    color: cccccc
+  - name: enhancement
+    color: 84b6eb
+  - name: good first issue
+    color: 7057ff
+  - name: help wanted
+    color: 159818
+  - name: invalid
+    color: e6e6e6
+  - name: mgmtlove
+    color: e11d21
+  - name: question
+    color: cc317c
+  - name: needinfo
+    color: fbca04
+  - name: wontfix
+    color: ffffff
+#  - name: first-timers-only
+#    # include the old name to rename an existing label
+#    oldname: Help Wanted
+
+# Collaborators: give specific users access to this repository.
+#collaborators:
+#  - username: purpleidea
+#    # Note: Only valid on organization-owned repositories.
+#    # The permission to grant the collaborator. Can be one of:
+#    # * `pull` - can pull, but not push to or administer this repository.
+#    # * `push` - can pull and push, but not administer this repository.
+#    # * `admin` - can pull, push and administer this repository.
+#    permission: push
+
+#  - username: hubot
+#    permission: pull
+
+# NOTE: The APIs needed for teams are not supported yet by GitHub Apps
+# https://developer.github.com/v3/apps/available-endpoints/
+#teams:
+#  - name: core
+#    permission: admin
+#  - name: docs
+#    permission: push

.github/workflows/test.yaml

@@ -0,0 +1,68 @@
+# Docs: https://help.github.com/en/articles/workflow-syntax-for-github-actions
+
+# If the name is omitted, it uses the filename instead.
+#name: Test
+on:
+  # Run on all pull requests.
+  pull_request:
+    #branches:
+    #- master
+  # Run on all pushes.
+  push:
+  # Run daily at 4am.
+  schedule:
+  - cron: 0 4 * * *
+
+jobs:
+  maketest:
+    name: Test (${{ matrix.test_block }}) on ${{ matrix.os }} with golang ${{ matrix.golang_version }}
+    runs-on: ${{ matrix.os }}
+    env:
+      GOPATH: /home/runner/work/mgmt/mgmt/go
+    strategy:
+      matrix:
+        # TODO: Add tip when it's supported: https://github.com/actions/setup-go/issues/21
+        os:
+          - ubuntu-latest
+          # macos tests are currently failing in CI
+          #- macos-latest
+        golang_version:
+          # TODO: add 1.21.x and tip
+          # minimum required and latest published go_version
+          - "1.20"
+        test_block:
+          - basic
+          - shell
+          - race
+      fail-fast: false
+
+    steps:
+      # Do not shallow fetch. The path can't be absolute, so we need to move it
+      # to the expected location later.
+      - name: Clone mgmt
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 0
+          path: ./go/src/github.com/purpleidea/mgmt
+
+      - name: Install Go ${{ matrix.golang_version }}
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ matrix.golang_version }}
+
+      # Install & configure ruby, fixes gem permissions error
+      - name: Install Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: head
+
+      - name: Install dependencies
+        working-directory: ./go/src/github.com/purpleidea/mgmt
+        run: |
+          make deps
+
+      - name: Run test
+        working-directory: ./go/src/github.com/purpleidea/mgmt
+        run: |
+          TEST_BLOCK="${{ matrix.test_block }}" make test

.gitignore

@@ -1,9 +1,20 @@
+.idea/
 .omv/
 .ssh/
 .vagrant/
-mgmt-documentation.pdf
+.envrc
 old/
 tmp/
+*WIP
 *_stringer.go
 mgmt
+mgmt.static
+# crossbuild artifacts
+build/mgmt-*
+mgmt.iml
 rpmbuild/
+releases/
+# vim swap files
+.*.sw[op]
+# prevent `echo foo 2>1` typo errors by making this file read-only
+1

.travis.yml

@@ -1,21 +1,54 @@
 language: go
-go:
-  - 1.4.3
-  - 1.5.3
-  - 1.6
-  - tip
-sudo: false
-before_install: 'git fetch --unshallow'
+os:
+  - linux
+go_import_path: github.com/purpleidea/mgmt
+sudo: true
+dist: xenial
+# travis requires that you update manually, and provides this key to trigger it
+apt:
+  update: true
+before_install:
+  # print some debug information to help catch the constant travis regressions
+  - if [ -e /etc/apt/sources.list.d/ ]; then sudo ls -l /etc/apt/sources.list.d/; fi
+  # workaround broken travis NO_PUBKEY errors
+  - if [ -e /etc/apt/sources.list.d/rabbitmq_rabbitmq-server.list ]; then sudo rm -f /etc/apt/sources.list.d/rabbitmq_rabbitmq-server.list; fi
+  - if [ -e /etc/apt/sources.list.d/github_git-lfs.list ]; then sudo rm -f /etc/apt/sources.list.d/github_git-lfs.list; fi
+  # as per a number of comments online, this might mitigate some flaky fails...
+  - if [[ "$TRAVIS_OS_NAME" != "osx" ]]; then sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 0C49F3730359A14518585931BC711F9BA15703C6; fi
+  # apt update tends to be flaky in travis, retry up to 3 times on failure
+  # https://docs.travis-ci.com/user/common-build-problems/#travis_retry
+  - if [[ "$TRAVIS_OS_NAME" != "osx" ]]; then travis_retry travis_retry sudo apt update; fi
+  - git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+  - git fetch --unshallow
 install: 'make deps'
-script: 'make test'
 matrix:
+  fast_finish: false
   allow_failures:
+  - go: 1.21.x
   - go: tip
-    - go: 1.4.3
+  - os: osx
+  # include only one build for osx for a quicker build as the nr. of these runners are sparse
+  include:
+  - name: "basic tests"
+    go: 1.20.x
+    env: TEST_BLOCK=basic
+  - name: "shell tests"
+    go: 1.20.x
+    env: TEST_BLOCK=shell
+  - name: "race tests"
+    go: 1.20.x
+    env: TEST_BLOCK=race
+  - go: 1.21.x
+  - go: tip
+  - os: osx
+script: 'TEST_BLOCK="$TEST_BLOCK" make test'
+
+# the "secure" channel value is the result of running: ./misc/travis-encrypt.sh
+# with a value of: irc.freenode.net#mgmtconfig to eliminate noise from forks...
 notifications:
   irc:
-    channels:
-      - "irc.freenode.net#mgmtconfig"
+    #channels:
+    #  - secure: htcuWAczm3C1zKC9vUfdRzhIXM1vtF+q0cLlQFXK1IQQlk693/pM30Mmf2L/9V2DVDeps+GyLdip0ARXD1DZEJV0lK+Ca1qbHdFP1r4Xv6l5+jaDb5Y88YU5LI8K758QShiZJojuQ1aO2j8xmmt9V0/5y5QwlpPeHbKYBOFPBX3HvlT9DhvwZNKGhBb4qJOEaPVOwq9IkN3DyQ456MHcJ3q3vF9Lb440uTuLsJNof2AbYZH8ZIHCSG2N8tBj2qhJOpWQboYtQJzE2pRaGkGBL4kYcHZSZMXX8sl4cBM1vx/IRUkvBxJUpLJz2gn/eRI+/gr59juZE2K0+FOLlx9dLnX626Y9xSViopBI6JsIoHJDqNC7aGaF2qaYulGYN65VNKVqmghjgt6JLmmiKeH10hYrJMMvt2rms8l4+5iwmCwXvhH/WU9edzk2p5wqERMnostJFEJib0zI3yzLoF0sdJs+veKtagzfayY2d2l7hlmt951IpqqVWldVgWUcQKVvi8gmRarbwFlK+5D7BEnkUDcLNly/cqf7BgEeX6YfF+FiR4pgfOhYvGCD+2q91NgWQXHBCxbyN0be1TVdkXD94f0Lkn94VyEJJ+PkPlG+rPgFwGcjqN4oEGkJeJmES2If05q2Ms1dJLwYQDL3+Py4lNMSdSWj24TzlFVhtwHepuw=
     template:
       - "%{repository} (%{commit}: %{author}): %{message}"
       - "More info : %{build_url}"
@@ -24,4 +57,7 @@ notifications:
     use_notice: false
     skip_join: false
   email:
-    - travis-ci@shubin.ca
+    recipients:
+      - secure: qNkgP6QLl6VXpFQIxas2wggxvIiOmm1/hGRXm4BXsSFzHsJPvMamA3E1HEC7H+luiWTny1jtGSGgTJPV9CX1LtQV0g0S4ThaAvWuKvk3rXO8IVd++iA/Lh1s1H6JdKM0dJtLqFICawjeci4tOQzSvrM2eCBWqT0UYsrQsGHB6AF31GNAH0Acqd5cYeL+ZpbCN+hQEznAZQ7546N25TwqieI8Lg7nisA+lwYYwsaC2+f5RIeyvvKjQv3wzEdBAQ9CI9WQiTOUBnUnyYxMrdomQ/XGF66QnZy9vq5nEP83IFtuhPvSamL7ceT+yJW0jDyBi8sYEV7On7eXzjyHbiYpF4YHcJrFnf5RyV4kQGd6/SC8iZwK4Is4eyeAjDFTC+JafLajw9R9x9bK43BwlRAWOZxjFKe0cU/BVAjmlz87vHgUho2P41+0a5XfajfU6VhA5QFPK6rNH7W1CnA7D/0LmS0yaqJM1OCrm6LfoZEMhe0DxTJ9uWJbr0x1sYao6q8H4xYk+fyRgoBAr2TxYU7kXx8ThiRdzuQ8izdbojlzTYLe8liZMIsjL0axLsLK7YBWrjJUcDFDjR/DqmVxPrvbVFbCi9ChmBw0WmbJvDY0FV8T8dO8wCjg9JEmprAmWPyq0g/F87LFK4tAZqQFJGjP1qwsR9jdwdNTKeCdY656f/Y=
+    on_failure: change
+    on_success: change

AUTHORS

@@ -1,7 +1,14 @@
 This is a list of authors/contributors to the mgmt project.
-If you're a contributor, please send a patch with your name.
+If you're a core contributor, we might ask you to send a patch with your name.
 If you appreciate the work of one of the contributors, thank them a beverage!
 For a more exhaustive list please run: git log --format='%aN' | sort -u
 This list is sorted alphabetically by first name.
 
+Felix Frank
 James Shubin
+Joe Groocock
+Johan Bloemberg
+Jonathan Gold
+Julien Pivotto
+Paul Morgan
+Samuel Gélineau

COPYING

@@ -1,21 +1,23 @@
-                    GNU AFFERO GENERAL PUBLIC LICENSE
-                       Version 3, 19 November 2007
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
 
- Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
                             Preamble
 
-  The GNU Affero General Public License is a free, copyleft license for
-software and other kinds of works, specifically designed to ensure
-cooperation with the community in the case of network server software.
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
 
   The licenses for most software and other practical works are designed
 to take away your freedom to share and change the works.  By contrast,
-our General Public Licenses are intended to guarantee your freedom to
+the GNU General Public License is intended to guarantee your freedom to
 share and change all versions of a program--to make sure it remains free
-software for all its users.
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
 
   When we speak of free software, we are referring to freedom, not
 price.  Our General Public Licenses are designed to make sure that you
@@ -24,34 +26,44 @@ them if you wish), that you receive source code or can get it if you
 want it, that you can change the software or use pieces of it in new
 free programs, and that you know you can do these things.
 
-  Developers that use our General Public Licenses protect your rights
-with two steps: (1) assert copyright on the software, and (2) offer
-you this License which gives you legal permission to copy, distribute
-and/or modify the software.
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
 
-  A secondary benefit of defending all users' freedom is that
-improvements made in alternate versions of the program, if they
-receive widespread use, become available for other developers to
-incorporate.  Many developers of free software are heartened and
-encouraged by the resulting cooperation.  However, in the case of
-software used on network servers, this result may fail to come about.
-The GNU General Public License permits making a modified version and
-letting the public access it on a server without ever releasing its
-source code to the public.
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
 
-  The GNU Affero General Public License is designed specifically to
-ensure that, in such cases, the modified source code becomes available
-to the community.  It requires the operator of a network server to
-provide the source code of the modified version running there to the
-users of that server.  Therefore, public use of a modified version, on
-a publicly accessible server, gives the public access to the source
-code of the modified version.
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
 
-  An older license, called the Affero General Public License and
-published by Affero, was designed to accomplish similar goals.  This is
-a different license, not a version of the Affero GPL, but Affero has
-released a new version of the Affero GPL which permits relicensing under
-this license.
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
 
   The precise terms and conditions for copying, distribution and
 modification follow.
@@ -60,7 +72,7 @@ modification follow.
 
   0. Definitions.
 
-  "This License" refers to version 3 of the GNU Affero General Public License.
+  "This License" refers to version 3 of the GNU General Public License.
 
   "Copyright" also means copyright-like laws that apply to other kinds of
 works, such as semiconductor masks.
@@ -537,45 +549,35 @@ to collect a royalty for further conveying from those to whom you convey
 the Program, the only way you could satisfy both those terms and this
 License would be to refrain entirely from conveying the Program.
 
-  13. Remote Network Interaction; Use with the GNU General Public License.
-
-  Notwithstanding any other provision of this License, if you modify the
-Program, your modified version must prominently offer all users
-interacting with it remotely through a computer network (if your version
-supports such interaction) an opportunity to receive the Corresponding
-Source of your version by providing access to the Corresponding Source
-from a network server at no charge, through some standard or customary
-means of facilitating copying of software.  This Corresponding Source
-shall include the Corresponding Source for any work covered by version 3
-of the GNU General Public License that is incorporated pursuant to the
-following paragraph.
+  13. Use with the GNU Affero General Public License.
 
   Notwithstanding any other provision of this License, you have
 permission to link or combine any covered work with a work licensed
-under version 3 of the GNU General Public License into a single
+under version 3 of the GNU Affero General Public License into a single
 combined work, and to convey the resulting work.  The terms of this
 License will continue to apply to the part which is the covered work,
-but the work with which it is combined will remain governed by version
-3 of the GNU General Public License.
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
 
   14. Revised Versions of this License.
 
   The Free Software Foundation may publish revised and/or new versions of
-the GNU Affero General Public License from time to time.  Such new versions
-will be similar in spirit to the present version, but may differ in detail to
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
 address new problems or concerns.
 
   Each version is given a distinguishing version number.  If the
-Program specifies that a certain numbered version of the GNU Affero General
+Program specifies that a certain numbered version of the GNU General
 Public License "or any later version" applies to it, you have the
 option of following the terms and conditions either of that numbered
 version or of any later version published by the Free Software
 Foundation.  If the Program does not specify a version number of the
-GNU Affero General Public License, you may choose any version ever published
+GNU General Public License, you may choose any version ever published
 by the Free Software Foundation.
 
   If the Program specifies that a proxy can decide which future
-versions of the GNU Affero General Public License can be used, that proxy's
+versions of the GNU General Public License can be used, that proxy's
 public statement of acceptance of a version permanently authorizes you
 to choose that version for the Program.
 
@@ -633,29 +635,40 @@ the "copyright" line and a pointer to where the full notice is found.
     Copyright (C) <year>  <name of author>
 
     This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Affero General Public License as published by
+    it under the terms of the GNU General Public License as published by
     the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
 
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU Affero General Public License for more details.
+    GNU General Public License for more details.
 
-    You should have received a copy of the GNU Affero General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 Also add information on how to contact you by electronic and paper mail.
 
-  If your software can interact with users remotely through a computer
-network, you should also make sure that it provides a way for users to
-get its source.  For example, if your program is a web application, its
-interface could display a "Source" link that leads users to an archive
-of the code.  There are many ways you could offer source, and different
-solutions will be better for different programs; see section 13 for the
-specific requirements.
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
 
   You should also get your employer (if you work as a programmer) or school,
 if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU AGPL, see
-<http://www.gnu.org/licenses/>.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/philosophy/why-not-lgpl.html>.

COPYRIGHT

@@ -1,16 +1,28 @@
 Mgmt
-Copyright (C) 2013-2016+ James Shubin and the project contributors
+Copyright (C) 2013-2024+ James Shubin and the project contributors
 Written by James Shubin <james@shubin.ca> and the project contributors
 
 This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published by
+it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.
 
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Affero General Public License for more details.
+GNU General Public License for more details.
 
-You should have received a copy of the GNU Affero General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Additional permission under GNU GPL version 3 section 7
+
+If you modify this program, or any covered work, by linking or combining it
+with embedded mcl code and modules (and that the embedded mcl code and
+modules which link with this program, contain a copy of their source code in
+the authoritative form) containing parts covered by the terms of any other
+license, the licensors of this program grant you additional permission to
+convey the resulting work. Furthermore, the licensors of this program grant
+the original author, James Shubin, additional permission to update this
+additional permission if he deems it necessary to achieve the goals of this
+additional permission.

DOCUMENTATION.md

@@ -1,198 +0,0 @@
-#mgmt
-
-<!--
-Mgmt
-Copyright (C) 2013-2016+ James Shubin and the project contributors
-Written by James Shubin <james@shubin.ca> and the project contributors
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
--->
-
-##mgmt by [James](https://ttboj.wordpress.com/)
-####Available from:
-####[https://github.com/purpleidea/mgmt/](https://github.com/purpleidea/mgmt/)
-
-####This documentation is available in: [Markdown](https://github.com/purpleidea/mgmt/blob/master/DOCUMENTATION.md) or [PDF](https://pdfdoc-purpleidea.rhcloud.com/pdf/https://github.com/purpleidea/mgmt/blob/master/DOCUMENTATION.md) format.
-
-####Table of Contents
-
-1. [Overview](#overview)
-2. [Project description - What the project does](#project-description)
-3. [Setup - Getting started with mgmt](#setup)
-4. [Features - All things mgmt can do](#features)
-	* [Autoedges - Automatic resource relationships](#autoedges)
-	* [Autogrouping - Automatic resource grouping](#autogrouping)
-5. [Usage/FAQ - Notes on usage and frequently asked questions](#usage-and-frequently-asked-questions)
-6. [Reference - Detailed reference](#reference)
-	* [Graph definition file](#graph-definition-file)
-	* [Command line](#command-line)
-7. [Examples - Example configurations](#examples)
-8. [Development - Background on module development and reporting bugs](#development)
-9. [Authors - Authors and contact information](#authors)
-
-##Overview
-
-The `mgmt` tool is a research prototype to demonstrate next generation config
-management techniques. Hopefully it will evolve into a useful, robust tool.
-
-##Project Description
-
-The mgmt tool is a distributed, event driven, config management tool, that
-supports parallel execution, and librarification to be used as the management
-foundation in and for, new and existing software.
-
-For more information, you may like to read some blog posts from the author:
-
-* [Next generation config mgmt](https://ttboj.wordpress.com/2016/01/18/next-generation-configuration-mgmt/)
-* [Automatic edges in mgmt](https://ttboj.wordpress.com/2016/03/14/automatic-edges-in-mgmt/)
-
-There is also an [introductory video](https://www.youtube.com/watch?v=GVhpPF0j-iE&html5=1) available.
-
-##Setup
-
-During this prototype phase, the tool can be run out of the source directory.
-You'll probably want to use ```./run.sh run --file examples/graph1.yaml``` to
-get started. Beware that this _can_ cause data loss. Understand what you're
-doing first, or perform these actions in a virtual environment such as the one
-provided by [Oh-My-Vagrant](https://github.com/purpleidea/oh-my-vagrant).
-
-##Features
-
-This section details the numerous features of mgmt and some caveats you might
-need to be aware of.
-
-###Autoedges
-
-Automatic edges, or AutoEdges, is the mechanism in mgmt by which it will
-automatically create dependencies for you between resources. For example,
-since mgmt can discover which files are installed by a package it will
-automatically ensure that any file resource you declare that matches a
-file installed by your package resource will only be processed after the
-package is installed.
-
-####Controlling autodeges
-
-Though autoedges is likely to be very helpful and avoid you having to declare
-all dependencies explicitly, there are cases where this behaviour is
-undesirable.
-
-Some distributions allow package installations to automatically start the
-service they ship. This can be problematic in the case of packages like MySQL
-as there are configuration options that need to be set before MySQL is ever
-started for the first time (or you'll need to wipe the data directory). In
-order to handle this situation you can disable autoedges per resource and
-explicitly declare that you want `my.cnf` to be written to disk before the
-installation of the `mysql-server` package.
-
-You can disable autoedges for a resource by setting the `autoedge` key on
-the meta attributes of that resource to `false`.
-
-###Autogrouping
-
-Automatic grouping or AutoGroup is the mechanism in mgmt by which it will
-automatically group multiple resource vertices into a single one. This is
-particularly useful for grouping multiple package resources into a single
-resource, since the multiple installations can happen together in a single
-transaction, which saves a lot of time because package resources typically have
-a large fixed cost to running (downloading and verifying the package repo) and
-if they are grouped they share this fixed cost. This grouping feature can be
-used for other use cases too.
-
-You can disable autogrouping for a resource by setting the `autogroup` key on
-the meta attributes of that resource to `false`.
-
-##Usage and frequently asked questions
-(Send your questions as a patch to this FAQ! I'll review it, merge it, and
-respond by commit with the answer.)
-
-###Why did you start this project?
-
-I wanted a next generation config management solution that didn't have all of
-the design flaws or limitations that the current generation of tools do, and no
-tool existed!
-
-###Why did you use etcd? What about consul?
-
-Etcd and consul are both written in golang, which made them the top two
-contenders for my prototype. Ultimately a choice had to be made, and etcd was
-chosen, but it was also somewhat arbitrary. If there is available interest,
-good reasoning, *and* patches, then we would consider either switching or
-supporting both, but this is not a high priority at this time.
-
-###You didn't answer my question, or I have a question!
-
-It's best to ask on [IRC](https://webchat.freenode.net/?channels=#mgmtconfig)
-to see if someone can help you. Once we get a big enough community going, we'll
-add a mailing list. If you don't get any response from the above, you can
-contact me through my [technical blog](https://ttboj.wordpress.com/contact/)
-and I'll do my best to help. If you have a good question, please add it as a
-patch to this documentation. I'll merge your question, and add a patch with the
-answer!
-
-##Reference
-Please note that there are a number of undocumented options. For more
-information on these options, please view the source at:
-[https://github.com/purpleidea/mgmt/](https://github.com/purpleidea/mgmt/).
-If you feel that a well used option needs documenting here, please patch it!
-
-###Overview of reference
-* [Graph definition file](#graph-definition-file): Main graph definition file.
-* [Command line](#command-line): Command line parameters.
-
-###Graph definition file
-graph.yaml is the compiled graph definition file. The format is currently
-undocumented, but by looking through the [examples/](https://github.com/purpleidea/mgmt/tree/master/examples)
-you can probably figure out most of it, as it's fairly intuitive.
-
-###Command line
-The main interface to the `mgmt` tool is the command line. For the most recent
-documentation, please run `mgmt --help`.
-
-####`--file <graph.yaml>`
-Point to a graph file to run.
-
-####`--converged-timeout <seconds>`
-Exit if the machine has converged for approximately this many seconds.
-
-####`--max-runtime <seconds>`
-Exit when the agent has run for approximately this many seconds. This is not
-generally recommended, but may be useful for users who know what they're doing.
-
-##Examples
-For example configurations, please consult the [examples/](https://github.com/purpleidea/mgmt/tree/master/examples) directory in the git
-source repository. It is available from:
-
-[https://github.com/purpleidea/mgmt/tree/master/examples](https://github.com/purpleidea/mgmt/tree/master/examples)
-
-##Development
-
-This is a project that I started in my free time in 2013. Development is driven
-by all of our collective patches! Dive right in, and start hacking!
-Please contact me if you'd like to invite me to speak about this at your event.
-
-You can follow along [on my technical blog](https://ttboj.wordpress.com/).
-
-To report any bugs, please file a ticket at: [https://github.com/purpleidea/mgmt/issues](https://github.com/purpleidea/mgmt/issues).
-
-##Authors
-
-Copyright (C) 2013-2016+ James Shubin and the project contributors
-
-Please see the
-[AUTHORS](https://github.com/purpleidea/mgmt/tree/master/AUTHORS) file
-for more information.
-
-* [github](https://github.com/purpleidea/)
-* [&#64;purpleidea](https://twitter.com/#!/purpleidea)
-* [https://ttboj.wordpress.com/](https://ttboj.wordpress.com/)

Makefile

@@ -1,34 +1,61 @@
 # Mgmt
-# Copyright (C) 2013-2016+ James Shubin and the project contributors
+# Copyright (C) 2013-2024+ James Shubin and the project contributors
 # Written by James Shubin <james@shubin.ca> and the project contributors
 #
 # This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
+# it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
+# GNU General Public License for more details.
 #
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# Additional permission under GNU GPL version 3 section 7
+#
+# If you modify this program, or any covered work, by linking or combining it
+# with embedded mcl code and modules (and that the embedded mcl code and
+# modules which link with this program, contain a copy of their source code in
+# the authoritative form) containing parts covered by the terms of any other
+# license, the licensors of this program grant you additional permission to
+# convey the resulting work. Furthermore, the licensors of this program grant
+# the original author, James Shubin, additional permission to update this
+# additional permission if he deems it necessary to achieve the goals of this
+# additional permission.
 
-SHELL = /bin/bash
-.PHONY: all version program path deps run race build clean test format docs rpmbuild mkdirs rpm srpm spec tar upload upload-sources upload-srpms upload-rpms copr
+SHELL = /usr/bin/env bash
+.PHONY: all art cleanart version program lang path deps run race generate build build-debug crossbuild clean test gofmt yamlfmt format docs
+.PHONY: rpmbuild mkdirs rpm srpm spec tar upload upload-sources upload-srpms upload-rpms upload-releases copr tag
+.PHONY: mkosi mkosi_fedora-latest mkosi_fedora-older mkosi_stream-latest mkosi_debian-stable mkosi_ubuntu-latest mkosi_archlinux
+.PHONY: release release_test releases_path release_binary_amd64 release_binary_arm64 release_fedora-latest release_fedora-older release_stream-latest release_debian-stable release_ubuntu-latest release_archlinux
+.PHONY: funcgen
 .SILENT: clean
 
-SVERSION := $(shell git describe --match '[0-9]*\.[0-9]*\.[0-9]*' --tags --dirty --always)
-VERSION := $(shell git describe --match '[0-9]*\.[0-9]*\.[0-9]*' --tags --abbrev=0)
+# a large amount of output from this `find`, can cause `make` to be much slower!
+GO_FILES := $(shell find * -name '*.go' -not -path 'old/*' -not -path 'tmp/*')
+MCL_FILES := $(shell find lang/ -name '*.mcl' -not -path 'old/*' -not -path 'tmp/*')
+
+SVERSION := $(or $(SVERSION),$(shell git describe --match '[0-9]*\.[0-9]*\.[0-9]*' --tags --dirty --always))
+VERSION := $(or $(VERSION),$(shell git describe --match '[0-9]*\.[0-9]*\.[0-9]*' --tags --abbrev=0))
 PROGRAM := $(shell echo $(notdir $(CURDIR)) | cut -f1 -d"-")
-OLDGOLANG := $(shell go version | grep -E 'go1.3|go1.4')
+PKGNAME := $(shell go list .)
 ifeq ($(VERSION),$(SVERSION))
 	RELEASE = 1
 else
 	RELEASE = untagged
 endif
-ARCH = $(shell arch)
+# debugging is harder if -trimpath is set, so disable it if env var is set
+# this is force enabled automatically when using the release target
+ifeq ($(MGMT_NOTRIMPATH),true)
+	TRIMPATH =
+else
+	TRIMPATH = -trimpath
+endif
+ARCH = $(uname -m)
 SPEC = rpmbuild/SPECS/$(PROGRAM).spec
 SOURCE = rpmbuild/SOURCES/$(PROGRAM)-$(VERSION).tar.bz2
 SRPM = rpmbuild/SRPMS/$(PROGRAM)-$(VERSION)-$(RELEASE).src.rpm
@@ -37,56 +64,219 @@ RPM = rpmbuild/RPMS/$(PROGRAM)-$(VERSION)-$(RELEASE).$(ARCH).rpm
 USERNAME := $(shell cat ~/.config/copr 2>/dev/null | grep username | awk -F '=' '{print $$2}' | tr -d ' ')
 SERVER = 'dl.fedoraproject.org'
 REMOTE_PATH = 'pub/alt/$(USERNAME)/$(PROGRAM)'
+ifneq ($(GOTAGS),)
+	BUILD_FLAGS = -tags '$(GOTAGS)'
+endif
+GOOSARCHES ?= linux/amd64 linux/ppc64 linux/ppc64le linux/arm64 darwin/amd64
 
-all: docs
+GOHOSTOS = $(shell go env GOHOSTOS)
+GOHOSTARCH = $(shell go env GOHOSTARCH)
+
+# The underscores separate the prefix name ("TOKEN") the distro ("BINARY",
+# "FEDORA-LATEST", etc...) and the arch ("AMD64"). The distro can have a dash.
+TOKEN_BINARY_AMD64 = $(shell grep -v '#' releases/binary-amd64.release)
+TOKEN_BINARY_ARM64 = $(shell grep -v '#' releases/binary-arm64.release)
+TOKEN_FEDORA-LATEST = $(shell grep -v '#' releases/fedora-latest.release)
+TOKEN_FEDORA-OLDER = $(shell grep -v '#' releases/fedora-older.release)
+TOKEN_STREAM-LATEST = $(shell grep -v '#' releases/stream-latest.release)
+TOKEN_DEBIAN-STABLE = $(shell grep -v '#' releases/debian-stable.release)
+TOKEN_UBUNTU-LATEST = $(shell grep -v '#' releases/ubuntu-latest.release)
+TOKEN_ARCHLINUX = $(shell grep -v '#' releases/archlinux.release)
+
+FILE_BINARY_AMD64 = mgmt-linux-amd64-$(VERSION)
+FILE_BINARY_ARM64 = mgmt-linux-arm64-$(VERSION)
+# TODO: add ARCH onto these at the end, eg _AMD64
+FILE_FEDORA-LATEST = mgmt-$(TOKEN_FEDORA-LATEST)-$(VERSION)-1.x86_64.rpm
+FILE_FEDORA-OLDER = mgmt-$(TOKEN_FEDORA-OLDER)-$(VERSION)-1.x86_64.rpm
+FILE_STREAM-LATEST = mgmt-$(TOKEN_STREAM-LATEST)-$(VERSION)-1.x86_64.rpm
+FILE_DEBIAN-STABLE = mgmt_$(TOKEN_DEBIAN-STABLE)_$(VERSION)_amd64.deb
+FILE_UBUNTU-LATEST = mgmt_$(TOKEN_UBUNTU-LATEST)_$(VERSION)_amd64.deb
+FILE_ARCHLINUX = mgmt-$(TOKEN_ARCHLINUX)-$(VERSION)-1-x86_64.pkg.tar.xz
+
+PKG_BINARY_AMD64 = releases/$(VERSION)/$(TOKEN_BINARY_AMD64)/$(FILE_BINARY_AMD64)
+PKG_BINARY_ARM64 = releases/$(VERSION)/$(TOKEN_BINARY_ARM64)/$(FILE_BINARY_ARM64)
+PKG_FEDORA-LATEST = releases/$(VERSION)/$(TOKEN_FEDORA-LATEST)/$(FILE_FEDORA-LATEST)
+PKG_FEDORA-OLDER = releases/$(VERSION)/$(TOKEN_FEDORA-OLDER)/$(FILE_FEDORA-OLDER)
+PKG_STREAM-LATEST = releases/$(VERSION)/$(TOKEN_STREAM-LATEST)/$(FILE_STREAM-LATEST)
+PKG_DEBIAN-STABLE = releases/$(VERSION)/$(TOKEN_DEBIAN-STABLE)/$(FILE_DEBIAN-STABLE)
+PKG_UBUNTU-LATEST = releases/$(VERSION)/$(TOKEN_UBUNTU-LATEST)/$(FILE_UBUNTU-LATEST)
+PKG_ARCHLINUX = releases/$(VERSION)/$(TOKEN_ARCHLINUX)/$(FILE_ARCHLINUX)
+
+DEP_BINARY_AMD64 =
+ifneq ($(TOKEN_BINARY_AMD64),)
+	DEP_BINARY_AMD64 = $(PKG_BINARY_AMD64)
+endif
+DEP_BINARY_ARM64 =
+ifneq ($(TOKEN_BINARY_ARM64),)
+	DEP_BINARY_ARM64 = $(PKG_BINARY_ARM64)
+endif
+DEP_FEDORA-LATEST =
+ifneq ($(TOKEN_FEDORA-LATEST),)
+	DEP_FEDORA-LATEST = $(PKG_FEDORA-LATEST)
+endif
+DEP_FEDORA-OLDER =
+ifneq ($(TOKEN_FEDORA-OLDER),)
+	DEP_FEDORA-OLDER = $(PKG_FEDORA-OLDER)
+endif
+DEP_STREAM-LATEST =
+ifneq ($(TOKEN_STREAM-LATEST),)
+	DEP_STREAM-LATEST = $(PKG_STREAM-LATEST)
+endif
+DEP_DEBIAN-STABLE =
+ifneq ($(TOKEN_DEBIAN-STABLE),)
+	DEP_DEBIAN-STABLE = $(PKG_DEBIAN-STABLE)
+endif
+DEP_UBUNTU-LATEST =
+ifneq ($(TOKEN_UBUNTU-LATEST),)
+	DEP_UBUNTU-LATEST = $(PKG_UBUNTU-LATEST)
+endif
+DEP_ARCHLINUX =
+ifneq ($(TOKEN_ARCHLINUX),)
+	DEP_ARCHLINUX = $(PKG_ARCHLINUX)
+endif
+
+SHA256SUMS = releases/$(VERSION)/SHA256SUMS
+SHA256SUMS_ASC = $(SHA256SUMS).asc
+
+default: build
+
+#
+#	art
+#
+art: art/mgmt_logo_default_symbol.png art/mgmt_logo_default_tall.png art/mgmt_logo_default_wide.png art/mgmt_logo_reversed_symbol.png art/mgmt_logo_reversed_tall.png art/mgmt_logo_reversed_wide.png art/mgmt_logo_white_symbol.png art/mgmt_logo_white_tall.png art/mgmt_logo_white_wide.png ## generate artwork
+
+cleanart:
+	rm -f art/mgmt_logo_default_symbol.png art/mgmt_logo_default_tall.png art/mgmt_logo_default_wide.png art/mgmt_logo_reversed_symbol.png art/mgmt_logo_reversed_tall.png art/mgmt_logo_reversed_wide.png art/mgmt_logo_white_symbol.png art/mgmt_logo_white_tall.png art/mgmt_logo_white_wide.png
+
+# NOTE: the widths are arbitrary
+art/mgmt_logo_default_symbol.png: art/mgmt_logo_default_symbol.svg
+	inkscape --export-background='#ffffff' --without-gui --export-png "$@" --export-width 300 $(@:png=svg)
+
+art/mgmt_logo_default_tall.png: art/mgmt_logo_default_tall.svg
+	inkscape --export-background='#ffffff' --without-gui --export-png "$@" --export-width 400 $(@:png=svg)
+
+art/mgmt_logo_default_wide.png: art/mgmt_logo_default_wide.svg
+	inkscape --export-background='#ffffff' --without-gui --export-png "$@" --export-width 800 $(@:png=svg)
+
+art/mgmt_logo_reversed_symbol.png: art/mgmt_logo_reversed_symbol.svg
+	inkscape --export-background='#231f20' --without-gui --export-png "$@" --export-width 300 $(@:png=svg)
+
+art/mgmt_logo_reversed_tall.png: art/mgmt_logo_reversed_tall.svg
+	inkscape --export-background='#231f20' --without-gui --export-png "$@" --export-width 400 $(@:png=svg)
+
+art/mgmt_logo_reversed_wide.png: art/mgmt_logo_reversed_wide.svg
+	inkscape --export-background='#231f20' --without-gui --export-png "$@" --export-width 800 $(@:png=svg)
+
+art/mgmt_logo_white_symbol.png: art/mgmt_logo_white_symbol.svg
+	inkscape --export-background='#231f20' --without-gui --export-png "$@" --export-width 300 $(@:png=svg)
+
+art/mgmt_logo_white_tall.png: art/mgmt_logo_white_tall.svg
+	inkscape --export-background='#231f20' --without-gui --export-png "$@" --export-width 400 $(@:png=svg)
+
+art/mgmt_logo_white_wide.png: art/mgmt_logo_white_wide.svg
+	inkscape --export-background='#231f20' --without-gui --export-png "$@" --export-width 800 $(@:png=svg)
+
+all: docs $(PROGRAM).static
 
 # show the current version
-version:
+version: ## show the current version
 	@echo $(VERSION)
 
-program:
+program: ## show the program name
 	@echo $(PROGRAM)
 
-path:
+path: ## create working paths
 	./misc/make-path.sh
 
-deps:
+deps: ## install system and golang dependencies
 	./misc/make-deps.sh
 
-run:
-	find -maxdepth 1 -type f -name '*.go' -not -name '*_test.go' | xargs go run -ldflags "-X main.program=$(PROGRAM) -X main.version=$(SVERSION)"
+run: ## run mgmt
+	find . -maxdepth 1 -type f -name '*.go' -not -name '*_test.go' | xargs go run -ldflags "-X main.program=$(PROGRAM) -X main.version=$(SVERSION)"
 
 # include race flag
 race:
-	find -maxdepth 1 -type f -name '*.go' -not -name '*_test.go' | xargs go run -race -ldflags "-X main.program=$(PROGRAM) -X main.version=$(SVERSION)"
+	find . -maxdepth 1 -type f -name '*.go' -not -name '*_test.go' | xargs go run -race -ldflags "-X main.program=$(PROGRAM) -X main.version=$(SVERSION)"
 
+generate:
+	go generate
+
+lang: ## generates the lexer/parser for the language frontend
+	@# recursively run make in child dir named lang
+	@$(MAKE) --quiet -C lang
+
+# build a `mgmt` binary for current host os/arch
+$(PROGRAM): build/mgmt-${GOHOSTOS}-${GOHOSTARCH} ## build an mgmt binary for current host os/arch
+	cp -a $< $@
+
+$(PROGRAM).static: $(GO_FILES) $(MCL_FILES) go.mod go.sum
+	@echo "Building: $(PROGRAM).static, version: $(SVERSION)..."
+	go generate
+	go build $(TRIMPATH) -a -installsuffix cgo -tags netgo -ldflags '-extldflags "-static" -X main.program=$(PROGRAM) -X main.version=$(SVERSION) -s -w' -o $(PROGRAM).static $(BUILD_FLAGS);
+
+build: LDFLAGS=-s -w ## build a fresh mgmt binary
 build: $(PROGRAM)
 
-$(PROGRAM): main.go
-	@echo "Building: $(PROGRAM), version: $(SVERSION)..."
-	go generate
-ifneq ($(OLDGOLANG),)
-	@# avoid equals sign in old golang versions eg in: -X foo=bar
-	go build -ldflags "-X main.program $(PROGRAM) -X main.version $(SVERSION)" -o $(PROGRAM);
-else
-	go build -ldflags "-X main.program=$(PROGRAM) -X main.version=$(SVERSION)" -o $(PROGRAM);
-endif
+build-debug: LDFLAGS=
+build-debug: $(PROGRAM)
 
-clean:
+# pattern rule target for (cross)building, mgmt-OS-ARCH will be expanded to the correct build
+# extract os and arch from target pattern
+GOOS=$(firstword $(subst -, ,$*))
+GOARCH=$(lastword $(subst -, ,$*))
+build/mgmt-%: $(GO_FILES) $(MCL_FILES) go.mod go.sum | lang funcgen
+	@echo "Building: $(PROGRAM), os/arch: $*, version: $(SVERSION)..."
+	time env GOOS=${GOOS} GOARCH=${GOARCH} go build $(TRIMPATH) -ldflags=$(PKGNAME)="-X main.program=$(PROGRAM) -X main.version=$(SVERSION) ${LDFLAGS}" -o $@ $(BUILD_FLAGS)
+
+# create a list of binary file names to use as make targets
+# to use this you might want to run something like:
+# GOOSARCHES='linux/arm64' GOTAGS='noaugeas novirt' make crossbuild
+# and the output will end up in build/
+crossbuild_targets = $(addprefix build/mgmt-,$(subst /,-,${GOOSARCHES}))
+crossbuild: ${crossbuild_targets}
+
+clean: ## clean things up
+	$(MAKE) --quiet -C test clean
+	$(MAKE) --quiet -C lang clean
+	$(MAKE) --quiet -C misc/mkosi clean
+	rm -f lang/core/generated_funcs.go || true
+	rm -f lang/core/generated_funcs_test.go || true
 	[ ! -e $(PROGRAM) ] || rm $(PROGRAM)
 	rm -f *_stringer.go	# generated by `go generate`
+	rm -f *_mock.go		# generated by `go generate`
+	# crossbuild artifacts
+	rm -f build/mgmt-*
 
-test:
+test: build ## run tests
+	@# recursively run make in child dir named test
+	@$(MAKE) --quiet -C test
 	./test.sh
 
-format:
-	find -type f -name '*.go' -not -path './old/*' -not -path './tmp/*' -exec gofmt -w {} \;
-	find -type f -name '*.yaml' -not -path './old/*' -not -path './tmp/*' -not -path './omv.yaml' -exec ruby -e "require 'yaml'; x=YAML.load_file('{}').to_yaml.each_line.map(&:rstrip).join(10.chr)+10.chr; File.open('{}', 'w').write x" \;
+# create all test targets for make tab completion (eg: make test-gofmt)
+test_suites=$(shell find test/ -maxdepth 1 -name test-* -exec basename {} .sh \;)
+# allow to run only one test suite at a time
+${test_suites}: test-%: build
+	./test.sh $*
 
-docs: $(PROGRAM)-documentation.pdf
+# targets to run individual shell tests (eg: make test-shell-load0)
+test_shell=$(shell find test/shell/ -maxdepth 1 -name "*.sh" -exec basename {} .sh \;)
+$(addprefix test-shell-,${test_shell}): test-shell-%: build
+	./test/test-shell.sh "$*.sh"
 
-$(PROGRAM)-documentation.pdf: DOCUMENTATION.md
-	pandoc DOCUMENTATION.md -o '$(PROGRAM)-documentation.pdf'
+gofmt:
+	# TODO: remove gofmt once goimports has a -s option
+	find . -maxdepth 9 -type f -name '*.go' -not -path './old/*' -not -path './tmp/*' -not -path './vendor/*' -exec gofmt -s -w {} \;
+	find . -maxdepth 9 -type f -name '*.go' -not -path './old/*' -not -path './tmp/*' -not -path './vendor/*' -exec goimports -w {} \;
+
+yamlfmt:
+	find . -maxdepth 3 -type f -name '*.yaml' -not -path './old/*' -not -path './tmp/*' -not -path './omv.yaml' -exec ruby -e "require 'yaml'; x=YAML.load_file('{}').to_yaml.each_line.map(&:rstrip).join(10.chr)+10.chr; File.open('{}', 'w').write x" \;
+
+format: gofmt yamlfmt ## format yaml and golang code
+
+docs: $(PROGRAM)-documentation.pdf ## generate docs
+
+$(PROGRAM)-documentation.pdf: docs/documentation.md
+	pandoc docs/documentation.md -o docs/'$(PROGRAM)-documentation.pdf'
 
 #
 #	build aliases
@@ -108,7 +298,7 @@ rpmbuild/SOURCES/: tar
 rpmbuild/SRPMS/: srpm
 rpmbuild/RPMS/: rpm
 
-upload: upload-sources upload-srpms upload-rpms
+upload: upload-sources upload-srpms upload-rpms ## upload sources
 	# do nothing
 
 #
@@ -130,8 +320,8 @@ $(SRPM): $(SPEC) $(SOURCE)
 #
 $(SPEC): rpmbuild/ spec.in
 	@echo Running templater...
-	#cat spec.in > $(SPEC)
-	sed -e s/__PROGRAM__/$(PROGRAM)/ -e s/__VERSION__/$(VERSION)/ -e s/__RELEASE__/$(RELEASE)/ < spec.in > $(SPEC)
+	cat spec.in > $(SPEC)
+	sed -e s/__PROGRAM__/$(PROGRAM)/g -e s/__VERSION__/$(VERSION)/g -e s/__RELEASE__/$(RELEASE)/g < spec.in > $(SPEC)
 	# append a changelog to the .spec file
 	git log --format="* %cd %aN <%aE>%n- (%h) %s%d%n" --date=local | sed -r 's/[0-9]+:[0-9]+:[0-9]+ //' >> $(SPEC)
 
@@ -213,10 +403,243 @@ upload-rpms: rpmbuild/RPMS/ rpmbuild/RPMS/SHA256SUMS rpmbuild/RPMS/SHA256SUMS.as
 		rsync -avz --prune-empty-dirs rpmbuild/RPMS/ $(SERVER):$(REMOTE_PATH)/RPMS/; \
 	fi
 
+upload-releases:
+	echo Running releases/ upload...
+	rsync -avz --exclude '.mkdir' --exclude 'mgmt-release.url' releases/ $(SERVER):$(REMOTE_PATH)/releases/
+
 #
 #	copr build
 #
-copr: upload-srpms
+copr: upload-srpms ## build in copr
 	./misc/copr-build.py https://$(SERVER)/$(REMOTE_PATH)/SRPMS/$(SRPM_BASE)
 
+#
+#	tag
+#
+tag: ## tags a new release
+	./misc/tag.sh
+
+#
+#	mkosi
+#
+mkosi: mkosi_fedora-latest mkosi_fedora-older mkosi_stream-latest mkosi_debian-stable mkosi_ubuntu-latest mkosi_archlinux ## builds distro packages via mkosi
+
+mkosi_fedora-latest: releases/$(VERSION)/.mkdir
+	@title='$@' ; echo "Generating: $${title#'mkosi_'} via mkosi..."
+	@title='$@' ; distro=$${title#'mkosi_'} ; ./misc/mkosi/make.sh $${distro} `realpath "releases/$(VERSION)/"`
+
+mkosi_fedora-older: releases/$(VERSION)/.mkdir
+	@title='$@' ; echo "Generating: $${title#'mkosi_'} via mkosi..."
+	@title='$@' ; distro=$${title#'mkosi_'} ; ./misc/mkosi/make.sh $${distro} `realpath "releases/$(VERSION)/"`
+
+mkosi_stream-latest: releases/$(VERSION)/.mkdir
+	@title='$@' ; echo "Generating: $${title#'mkosi_'} via mkosi..."
+	@title='$@' ; distro=$${title#'mkosi_'} ; ./misc/mkosi/make.sh $${distro} `realpath "releases/$(VERSION)/"`
+
+mkosi_debian-stable: releases/$(VERSION)/.mkdir
+	@title='$@' ; echo "Generating: $${title#'mkosi_'} via mkosi..."
+	@title='$@' ; distro=$${title#'mkosi_'} ; ./misc/mkosi/make.sh $${distro} `realpath "releases/$(VERSION)/"`
+
+mkosi_ubuntu-latest: releases/$(VERSION)/.mkdir
+	@title='$@' ; echo "Generating: $${title#'mkosi_'} via mkosi..."
+	@title='$@' ; distro=$${title#'mkosi_'} ; ./misc/mkosi/make.sh $${distro} `realpath "releases/$(VERSION)/"`
+
+mkosi_archlinux: releases/$(VERSION)/.mkdir
+	@title='$@' ; echo "Generating: $${title#'mkosi_'} via mkosi..."
+	@title='$@' ; distro=$${title#'mkosi_'} ; ./misc/mkosi/make.sh $${distro} `realpath "releases/$(VERSION)/"`
+
+#
+#	release
+#
+release: TRIMPATH = -trimpath
+release: releases/$(VERSION)/mgmt-release.url ## generates and uploads a release
+
+releases_path:
+	@#Don't put any other output or dependencies in here or they'll show!
+	@echo "releases/$(VERSION)/"
+
+release_test: $(DEP_BINARY_AMD64) $(DEP_BINARY_ARM64) $(DEP_FEDORA-LATEST) $(DEP_FEDORA-OLDER) $(DEP_STREAM-LATEST) $(DEP_DEBIAN-STABLE) $(DEP_UBUNTU-LATEST) $(DEP_ARCHLINUX) $(SHA256SUMS_ASC)
+	@echo '$$< denotes ‘the first dependency of the current rule’.'
+	@echo '> '"$<"
+	@echo
+	@echo '$$@ denotes ‘the target of the current rule’.'
+	@echo '> '"$@"
+	@echo
+	@echo '$$^ denotes ‘the dependencies of the current rule’.'
+	@echo '> '"$^"
+	@echo
+	@echo '$$* denotes ‘the stem with which the pattern of the current rule matched’.'
+	@echo '> '"$*"
+	@echo
+	@echo "TOKEN_BINARY_AMD64: $(TOKEN_BINARY_AMD64)"
+	@echo "DEP_BINARY_AMD64: $(DEP_BINARY_AMD64)"
+	@echo
+	@echo "TOKEN_BINARY_ARM64: $(TOKEN_BINARY_ARM64)"
+	@echo "DEP_BINARY_ARM64: $(DEP_BINARY_ARM64)"
+	@echo
+	@echo "TOKEN_FEDORA-LATEST: $(TOKEN_FEDORA-LATEST)"
+	@echo "DEP_FEDORA-LATEST: $(DEP_FEDORA-LATEST)"
+	@echo
+	@echo "TOKEN_FEDORA-OLDER: $(TOKEN_FEDORA-OLDER)"
+	@echo "DEP_FEDORA-OLDER: $(DEP_FEDORA-OLDER)"
+	@echo
+	@echo "TOKEN_STREAM-LATEST: $(TOKEN_STREAM-LATEST)"
+	@echo "DEP_STREAM-LATEST: $(DEP_STREAM-LATEST)"
+	@echo
+	@echo "TOKEN_DEBIAN-STABLE: $(TOKEN_DEBIAN-STABLE)"
+	@echo "DEP_DEBIAN-STABLE: $(DEP_DEBIAN-STABLE)"
+	@echo
+	@echo "TOKEN_UBUNTU-LATEST: $(TOKEN_UBUNTU-LATEST)"
+	@echo "DEP_UBUNTU-LATEST: $(DEP_UBUNTU-LATEST)"
+	@echo
+	@echo "TOKEN_ARCHLINUX: $(TOKEN_ARCHLINUX)"
+	@echo "DEP_ARCHLINUX: $(DEP_ARCHLINUX)"
+
+release_binary_amd64: $(PKG_BINARY_AMD64)
+release_binary_arm64: $(PKG_BINARY_ARM64)
+release_fedora-latest: $(PKG_FEDORA-LATEST)
+release_fedora-older: $(PKG_FEDORA-OLDER)
+release_stream-latest: $(PKG_STREAM-LATEST)
+release_debian-stable: $(PKG_DEBIAN-STABLE)
+release_ubuntu-latest: $(PKG_UBUNTU-LATEST)
+release_archlinux: $(PKG_ARCHLINUX)
+
+releases/$(VERSION)/mgmt-release.url: $(DEP_BINARY_AMD64) $(DEP_BINARY_ARM64) $(DEP_FEDORA-LATEST) $(DEP_FEDORA-OLDER) $(DEP_STREAM-LATEST) $(DEP_DEBIAN-STABLE) $(DEP_UBUNTU-LATEST) $(DEP_ARCHLINUX) $(SHA256SUMS_ASC)
+	@echo "Pushing git tag $(VERSION) to origin..."
+	git push origin $(VERSION)
+	@echo "Creating github release..."
+	hub release create \
+		-F <( echo -e "$(VERSION)\n";echo "Verify the signatures of all packages before you use them. The signing key can be downloaded from https://purpleidea.com/contact/#pgp-key to verify the release." ) \
+		` [ -e $(PKG_BINARY_AMD64) ] && printf -- "-a $(PKG_BINARY_AMD64)" ` \
+		` [ -e $(PKG_BINARY_ARM64) ] && printf -- "-a $(PKG_BINARY_ARM64)" ` \
+		` [ -e $(PKG_FEDORA-LATEST) ] && printf -- "-a $(PKG_FEDORA-LATEST)" ` \
+		` [ -e $(PKG_FEDORA-OLDER) ] && printf -- "-a $(PKG_FEDORA-OLDER)" ` \
+		` [ -e $(PKG_STREAM-LATEST) ] && printf -- "-a $(PKG_STREAM-LATEST)" ` \
+		` [ -e $(PKG_DEBIAN-STABLE) ] && printf -- "-a $(PKG_DEBIAN-STABLE)" ` \
+		` [ -e $(PKG_UBUNTU-LATEST) ] && printf -- "-a $(PKG_UBUNTU-LATEST)" ` \
+		` [ -e $(PKG_ARCHLINUX) ] && printf -- "-a $(PKG_ARCHLINUX)" ` \
+		-a $(SHA256SUMS_ASC) \
+		$(VERSION) \
+		> releases/$(VERSION)/mgmt-release.url \
+		&& cat releases/$(VERSION)/mgmt-release.url \
+		|| rm -f releases/$(VERSION)/mgmt-release.url
+
+releases/$(VERSION)/.mkdir:
+	mkdir -p \
+	` [ "$(TOKEN_BINARY_AMD64)" != "" ] && printf -- "releases/$(VERSION)/$(TOKEN_BINARY_AMD64)/" ` \
+	` [ "$(TOKEN_BINARY_ARM64)" != "" ] && printf -- "releases/$(VERSION)/$(TOKEN_BINARY_ARM64)/" ` \
+	` [ "$(TOKEN_FEDORA-LATEST)" != "" ] && printf -- "releases/$(VERSION)/$(TOKEN_FEDORA-LATEST)/" ` \
+	` [ "$(TOKEN_FEDORA-OLDER)" != "" ] && printf -- "releases/$(VERSION)/$(TOKEN_FEDORA-OLDER)/" ` \
+	` [ "$(TOKEN_STREAM-LATEST)" != "" ] && printf -- "releases/$(VERSION)/$(TOKEN_STREAM-LATEST)/" ` \
+	` [ "$(TOKEN_DEBIAN-STABLE)" != "" ] && printf -- "releases/$(VERSION)/$(TOKEN_DEBIAN-STABLE)/" ` \
+	` [ "$(TOKEN_UBUNTU-LATEST)" != "" ] && printf -- "releases/$(VERSION)/$(TOKEN_UBUNTU-LATEST)/" ` \
+	` [ "$(TOKEN_ARCHLINUX)" != "" ] && printf -- "releases/$(VERSION)/$(TOKEN_ARCHLINUX)/" ` \
+	&& touch releases/$(VERSION)/.mkdir
+
+# These are defined conditionally, since if the token is empty, they warn!
+ifneq ($(TOKEN_BINARY_AMD64),)
+$(PKG_BINARY_AMD64): build/mgmt-linux-amd64 releases/$(VERSION)/.mkdir
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Building: $${distro} package..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; cp -a build/mgmt-linux-amd64 $(PKG_BINARY_AMD64)
+endif
+ifneq ($(TOKEN_BINARY_ARM64),)
+$(PKG_BINARY_ARM64): build/mgmt-linux-arm64 releases/$(VERSION)/.mkdir
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Building: $${distro} package..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; cp -a build/mgmt-linux-arm64 $(PKG_BINARY_ARM64)
+endif
+ifneq ($(TOKEN_FEDORA-LATEST),)
+releases/$(VERSION)/$(TOKEN_FEDORA-LATEST)/changelog: $(PROGRAM) releases/$(VERSION)/.mkdir
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Generating: $${distro} changelog..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/make-rpm-changelog.sh "$${distro}" $(VERSION)
+
+$(PKG_FEDORA-LATEST): releases/$(VERSION)/$(TOKEN_FEDORA-LATEST)/changelog
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Building: $${distro} package..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/fpm-pack.sh $${distro} $(VERSION) "$(FILE_FEDORA-LATEST)" libvirt-devel augeas-devel
+endif
+ifneq ($(TOKEN_FEDORA-OLDER),)
+releases/$(VERSION)/$(TOKEN_FEDORA-OLDER)/changelog: $(PROGRAM) releases/$(VERSION)/.mkdir
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Generating: $${distro} changelog..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/make-rpm-changelog.sh "$${distro}" $(VERSION)
+
+$(PKG_FEDORA-OLDER): releases/$(VERSION)/$(TOKEN_FEDORA-OLDER)/changelog
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Building: $${distro} package..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/fpm-pack.sh $${distro} $(VERSION) "$(FILE_FEDORA-OLDER)" libvirt-devel augeas-devel
+endif
+ifneq ($(TOKEN_STREAM-LATEST),)
+releases/$(VERSION)/$(TOKEN_STREAM-LATEST)/changelog: $(PROGRAM) releases/$(VERSION)/.mkdir
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Generating: $${distro} changelog..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/make-rpm-changelog.sh "$${distro}" $(VERSION)
+
+$(PKG_STREAM-LATEST): releases/$(VERSION)/$(TOKEN_STREAM-LATEST)/changelog
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Building: $${distro} package..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/fpm-pack.sh $${distro} $(VERSION) "$(FILE_STREAM-LATEST)" libvirt-devel augeas-devel
+endif
+ifneq ($(TOKEN_DEBIAN-STABLE),)
+releases/$(VERSION)/$(TOKEN_DEBIAN-STABLE)/changelog: $(PROGRAM) releases/$(VERSION)/.mkdir
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Generating: $${distro} changelog..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/make-deb-changelog.sh "$${distro}" $(VERSION)
+
+$(PKG_DEBIAN-STABLE): releases/$(VERSION)/$(TOKEN_DEBIAN-STABLE)/changelog
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Building: $${distro} package..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/fpm-pack.sh $${distro} $(VERSION) "$(FILE_DEBIAN-STABLE)" libvirt-dev libaugeas-dev
+endif
+ifneq ($(TOKEN_UBUNTU-LATEST),)
+releases/$(VERSION)/$(TOKEN_UBUNTU-LATEST)/changelog: $(PROGRAM) releases/$(VERSION)/.mkdir
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Generating: $${distro} changelog..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/make-deb-changelog.sh "$${distro}" $(VERSION)
+
+$(PKG_UBUNTU-LATEST): releases/$(VERSION)/$(TOKEN_UBUNTU-LATEST)/changelog
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Building: $${distro} package..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/fpm-pack.sh $${distro} $(VERSION) "$(FILE_UBUNTU-LATEST)" libvirt-dev libaugeas-dev
+endif
+ifneq ($(TOKEN_ARCHLINUX),)
+$(PKG_ARCHLINUX): $(PROGRAM) releases/$(VERSION)/.mkdir
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; echo "Building: $${distro} package..."
+	@title='$(@D)' ; distro=$${title#'releases/$(VERSION)/'} ; ./misc/fpm-pack.sh $${distro} $(VERSION) "$(FILE_ARCHLINUX)" libvirt augeas
+endif
+
+$(SHA256SUMS): $(DEP_BINARY_AMD64) $(DEP_BINARY_ARM64) $(DEP_FEDORA-LATEST) $(DEP_FEDORA-OLDER) $(DEP_STREAM-LATEST) $(DEP_DEBIAN-STABLE) $(DEP_UBUNTU-LATEST) $(DEP_ARCHLINUX)
+	@# remove the directory separator in the SHA256SUMS file
+	@echo "Generating: sha256 sum..."
+	sha256sum \
+	` [ -e $(PKG_BINARY_AMD64) ] && printf -- "$(PKG_BINARY_AMD64)" ` \
+	` [ -e $(PKG_BINARY_ARM64) ] && printf -- "$(PKG_BINARY_ARM64)" ` \
+	` [ -e $(PKG_FEDORA-LATEST) ] && printf -- "$(PKG_FEDORA-LATEST)" ` \
+	` [ -e $(PKG_FEDORA-OLDER) ] && printf -- "$(PKG_FEDORA-OLDER)" ` \
+	` [ -e $(PKG_STREAM-LATEST) ] && printf -- "$(PKG_STREAM-LATEST)" ` \
+	` [ -e $(PKG_DEBIAN-STABLE) ] && printf -- "$(PKG_DEBIAN-STABLE)" ` \
+	` [ -e $(PKG_UBUNTU-LATEST) ] && printf -- "$(PKG_UBUNTU-LATEST)" ` \
+	` [ -e $(PKG_ARCHLINUX) ] && printf -- "$(PKG_ARCHLINUX)" ` \
+	| awk -F '/| ' '{print $$1"  "$$6}' > $(SHA256SUMS)
+
+$(SHA256SUMS_ASC): $(SHA256SUMS)
+	@echo "Signing sha256 sum..."
+	gpg2 --yes --clearsign $(SHA256SUMS)
+
+build_container: ## builds the container
+	docker build -t purpleidea/mgmt-build -f docker/Dockerfile.build .
+	docker run -td --name mgmt-build purpleidea/mgmt-build
+	docker cp mgmt-build:/root/gopath/src/github.com/purpleidea/mgmt/mgmt .
+	docker build -t purpleidea/mgmt -f docker/Dockerfile.static .
+	docker rm mgmt-build || true
+
+clean_container: ## removes the container
+	docker rmi purpleidea/mgmt-build
+	docker rmi purpleidea/mgmt
+
+help: ## show this help screen
+	@echo 'Usage: make <OPTIONS> ... <TARGETS>'
+	@echo ''
+	@echo 'Available targets are:'
+	@echo ''
+	@grep -E '^[ a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo ''
+
+funcgen: lang/core/generated_funcs.go
+
+lang/core/generated_funcs.go: lang/funcs/funcgen/*.go lang/core/funcgen.yaml lang/funcs/funcgen/templates/generated_funcs.go.tpl
+	@echo "Generating: funcs..."
+	@go run `find lang/funcs/funcgen/ -maxdepth 1 -type f -name '*.go' -not -name '*_test.go'` -templates=lang/funcs/funcgen/templates/generated_funcs.go.tpl >/dev/null
+
 # vim: ts=8

README.md

@@ -1,74 +1,134 @@
-# *mgmt*: This is: mgmt!
+# *mgmt*: next generation config management!
 
-[![Build Status](https://secure.travis-ci.org/purpleidea/mgmt.png?branch=master)](http://travis-ci.org/purpleidea/mgmt)
-[![Documentation](https://img.shields.io/docs/markdown.png)](DOCUMENTATION.md)
-[![IRC](https://img.shields.io/irc/%23mgmtconfig.png)](https://webchat.freenode.net/?channels=#mgmtconfig)
-[![Jenkins](https://img.shields.io/jenkins/status.png)](https://ci.centos.org/job/purpleidea-mgmt/)
-[![COPR](https://img.shields.io/copr/builds.png)](https://copr.fedoraproject.org/coprs/purpleidea/mgmt/)
+[![mgmt!](art/mgmt.png)](art/)
+
+[![Go Report Card](https://goreportcard.com/badge/github.com/purpleidea/mgmt?style=flat-square)](https://goreportcard.com/report/github.com/purpleidea/mgmt)
+[![Build Status](https://github.com/purpleidea/mgmt/workflows/.github/workflows/test.yaml/badge.svg)](https://github.com/purpleidea/mgmt/actions/)
+[![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=flat-square)](https://godocs.io/github.com/purpleidea/mgmt)
+[![Matrix](https://img.shields.io/badge/matrix-%23mgmtconfig-orange.svg?style=flat-square)](https://matrix.to/#/#mgmtconfig:matrix.org)
+[![IRC](https://img.shields.io/badge/irc-%23mgmtconfig-orange.svg?style=flat-square)](https://web.libera.chat/?channels=#mgmtconfig)
+[![Patreon](https://img.shields.io/badge/patreon-donate-yellow.svg?style=flat-square)](https://www.patreon.com/purpleidea)
+[![Liberapay](https://img.shields.io/badge/liberapay-donate-yellow.svg?style=flat-square)](https://liberapay.com/purpleidea/donate)
+
+## About:
+
+`Mgmt` is a real-time automation tool. It is familiar to existing configuration
+management software, but is drastically more powerful as it can allow you to
+build real-time, closed-loop feedback systems, in a very safe way, and with a
+surprisingly small amout of our `mcl` code. For example, the following code will
+ensure that your file server is set to read-only when it's friday.
+
+```mcl
+import "datetime"
+$is_friday = datetime.weekday(datetime.now()) == "friday"
+file "/srv/files/" {
+	state => $const.res.file.state.exists,
+	mode => if $is_friday { # this updates the mode, the instant it changes!
+		"0550"
+	} else {
+		"0770"
+	},
+}
+```
+
+It can run continuously, intermittently, or on-demand, and in the first case, it
+will guarantee that your system is always in the desired state for that instant!
+In this mode it can run as a decentralized cluster of agents across your
+network, each exchanging information with the others in real-time, to respond to
+your changing needs. For example, if you want to ensure that some resource runs
+on a maximum of two hosts in your cluster, you can specify that as well:
+
+```mcl
+import "sys"
+import "world"
+
+# we'll set a few scheduling options:
+$opts = struct{strategy => "rr", max => 2, ttl => 10,}
+
+# schedule in a particular namespace with options:
+$set = world.schedule("xsched", $opts)
+
+if sys.hostname() in $set {
+	# use your imagination to put something more complex right here...
+	print "i got scheduled" {} # this will run on the chosen machines
+}
+```
+
+As you add and remove hosts from the cluster, the real-time `schedule` function
+will dynamically pick up to two hosts from the available pool. These specific
+functions aren't intrinsic to the core design, and new ones can be easily added.
+
+Please read on if you'd like to learn more...
 
 ## Community:
-Come join us on IRC in [#mgmtconfig](https://webchat.freenode.net/?channels=#mgmtconfig) on Freenode!
-You may like the [#mgmtconfig](https://twitter.com/hashtag/mgmtconfig) hashtag if you're on [Twitter](https://twitter.com/#!/purpleidea).
 
-## Questions:
-Please join the [#mgmtconfig](https://webchat.freenode.net/?channels=#mgmtconfig) IRC community!
-If you have a well phrased question that might benefit others, consider asking it by sending a patch to the documentation [FAQ](https://github.com/purpleidea/mgmt/blob/master/DOCUMENTATION.md#usage-and-frequently-asked-questions) section. I'll merge your question, and a patch with the answer!
+Come join us in the `mgmt` community!
 
-## Quick start:
-* Either get the golang dependencies on your own, or run `make deps` if you're comfortable with how we install them.
-* Run `make build` to get a freshly built `mgmt` binary.
-* Run `cd $(mktemp --tmpdir -d tmp.XXX) && etcd` to get etcd running. The `mgmt` software will do this automatically for you in the future.
-* Run `time ./mgmt run --file examples/graph0.yaml --converged-timeout=1` to try out a very simple example!
-* To run continuously in the default mode of operation, omit the `--converged-timeout` option.
-* Have fun hacking on our future technology!
+| Medium | Link |
+|---|---|
+| Matrix | [#mgmtconfig](https://matrix.to/#/#mgmtconfig:matrix.org) on Matrix.org |
+| IRC | [#mgmtconfig](https://web.libera.chat/?channels=#mgmtconfig) on Libera.Chat |
+| Twitter | [@mgmtconfig](https://twitter.com/mgmtconfig) & [#mgmtconfig](https://twitter.com/hashtag/mgmtconfig) |
+| Mailing list | [looking for a new home, suggestions welcome](https://gitlab.freedesktop.org/freedesktop/freedesktop/-/issues/1082) |
+| Patreon | [purpleidea](https://www.patreon.com/purpleidea) on Patreon |
 
-## Examples:
-Please look in the [examples/](examples/) folder for more examples!
+## Status:
+
+Mgmt is a next generation automation tool. It has similarities to other tools in
+the configuration management space, but has a fast, modern, distributed systems
+approach. The project contains an engine and a language.
+[Please have a look at an introductory video or blog post.](docs/on-the-web.md)
+
+Mgmt is a fairly new project. It is usable today, but not yet feature complete.
+With your help you'll be able to influence our design and get us to 1.0 sooner!
+Interested users should read the [quick start guide](docs/quick-start-guide.md).
 
 ## Documentation:
-Please see: [DOCUMENTATION.md](DOCUMENTATION.md) or [PDF](https://pdfdoc-purpleidea.rhcloud.com/pdf/https://github.com/purpleidea/mgmt/blob/master/DOCUMENTATION.md).
 
-## Roadmap:
-Please see: [TODO.md](TODO.md) for a list of upcoming work and TODO items.
-Please get involved by working on one of these items or by suggesting something else!
-Feel free to grab one of the straightforward [#mgmtlove](https://github.com/purpleidea/mgmt/labels/mgmtlove) issues if you're a first time contributor to the project or if you're unsure about what to hack on!
+Please read, enjoy and help improve our documentation!
+
+| Documentation | Additional Notes |
+|---|---|
+| [quick start guide](docs/quick-start-guide.md) | for everyone |
+| [frequently asked questions](docs/faq.md) | for everyone |
+| [general documentation](docs/documentation.md) | for everyone |
+| [language guide](docs/language-guide.md) | for everyone |
+| [function guide](docs/function-guide.md) | for mgmt developers |
+| [resource guide](docs/resource-guide.md) | for mgmt developers |
+| [style guide](docs/style-guide.md) | for mgmt developers |
+| [godoc API reference](https://godoc.org/github.com/purpleidea/mgmt) | for mgmt developers |
+| [prometheus guide](docs/prometheus.md) | for everyone |
+| [development](docs/development.md) | for mgmt developers |
+| [videos](docs/on-the-web.md) | for everyone |
+| [blogs](docs/on-the-web.md) | for everyone |
+
+## Questions:
+
+Please ask in the [community](#community)!
+If you have a well phrased question that might benefit others, consider asking
+it by sending a patch to the [FAQ](docs/faq.md) section. I'll merge your
+question, and a patch with the answer!
+
+## Get involved:
+
+Feel free to grab one of the straightforward [#mgmtlove](https://github.com/purpleidea/mgmt/labels/mgmtlove)
+issues if you're a first time contributor to the project or if you're unsure
+about what to hack on! Please get involved by working on one of these items or
+by suggesting something else! There are some lower priority issues and harder
+issues available in our [TODO](TODO.md) file. Please have a look.
 
 ## Bugs:
-Please set the `DEBUG` constant in [main.go](https://github.com/purpleidea/mgmt/blob/master/main.go) to `true`, and post the logs when you report the [issue](https://github.com/purpleidea/mgmt/issues).
-Bonus points if you provide a [shell](https://github.com/purpleidea/mgmt/tree/master/test/shell) or [OMV](https://github.com/purpleidea/mgmt/tree/master/test/omv) reproducible test case.
-Feel free to read my article on [debugging golang programs](https://ttboj.wordpress.com/2016/02/15/debugging-golang-programs/).
 
-## Dependencies:
-* golang 1.4 or higher (required, available in most distros)
-* golang libraries (required, available with `go get`)
-
-        go get github.com/coreos/etcd/client
-        go get gopkg.in/yaml.v2
-        go get gopkg.in/fsnotify.v1
-        go get github.com/codegangsta/cli
-        go get github.com/coreos/go-systemd/dbus
-        go get github.com/coreos/go-systemd/util
-
-* stringer (required for building), available as a package on some platforms, otherwise via `go get`
-
-        go get golang.org/x/tools/cmd/stringer
-
-* pandoc (optional, for building a pdf of the documentation)
-* graphviz (optional, for building a visual representation of the graph)
+Please set the `DEBUG` constant in [main.go](https://github.com/purpleidea/mgmt/blob/master/main.go)
+to `true`, and post the logs when you report the [issue](https://github.com/purpleidea/mgmt/issues).
+Feel free to read my article on [debugging golang programs](https://purpleidea.com/blog/2016/02/15/debugging-golang-programs/).
 
 ## Patches:
+
 We'd love to have your patches! Please send them by email, or as a pull request.
 
 ## On the web:
-* Introductory blog post: [https://ttboj.wordpress.com/2016/01/18/next-generation-configuration-mgmt/](https://ttboj.wordpress.com/2016/01/18/next-generation-configuration-mgmt/)
-* Introductory recording from DevConf.cz 2016: [https://www.youtube.com/watch?v=GVhpPF0j-iE&html5=1](https://www.youtube.com/watch?v=GVhpPF0j-iE&html5=1)
-* Introductory recording from CfgMgmtCamp.eu 2016: [https://www.youtube.com/watch?v=fNeooSiIRnA&html5=1](https://www.youtube.com/watch?v=fNeooSiIRnA&html5=1)
-* Julian Dunn at CfgMgmtCamp.eu 2016: [https://www.youtube.com/watch?v=kfF9IATUask&t=1949&html5=1](https://www.youtube.com/watch?v=kfF9IATUask&t=1949&html5=1)
-* Walter Heck at CfgMgmtCamp.eu 2016: [http://www.slideshare.net/olindata/configuration-management-time-for-a-4th-generation/3](http://www.slideshare.net/olindata/configuration-management-time-for-a-4th-generation/3)
-* Marco Marongiu on mgmt: [http://syslog.me/2016/02/15/leap-or-die/](http://syslog.me/2016/02/15/leap-or-die/)
-* Felix Frank on puppet to mgmt "transpiling" [https://ffrank.github.io/features/2016/02/18/from-catalog-to-mgmt/](https://ffrank.github.io/features/2016/02/18/from-catalog-to-mgmt/)
-* Blog post on automatic edges and the pkg resource: [https://ttboj.wordpress.com/2016/03/14/automatic-edges-in-mgmt/](https://ttboj.wordpress.com/2016/03/14/automatic-edges-in-mgmt/)
 
-##
+[Blog posts and recorded talks about mgmt are listed here!](docs/on-the-web.md)
 
 Happy hacking!

THANKS

@@ -9,10 +9,16 @@ Chris Wright - For encouraging me to continue work on my prototype.
 
 Daniel Riek - For supporting and sheltering this project from bureaucracy.
 
+Diego Ongaro - For good chats, particularly around distributed systems.
+
+Felix Frank - For taking a difficult problem and building an inspiring solution.
+
 Ira Cooper - For having an algorithmic design discussion with me.
 
 Jeff Darcy - For some algorithm recommendations, and NACKing my TopoSort idea!
 
 Red Hat, inc. - For paying my salary, thus financially supporting my hacking.
 
+Samuel Gélineau - For help with programming language theory and design.
+
 And many others...

TODO.md

@@ -1,43 +1,90 @@
 # TODO
-If you're looking for something to do, look here!
-Let us know if you're working on one of the items.
+
+Here is a TODO list of longstanding items that are either lower-priority, or
+more involved in terms of time, skill-level, and/or motivation.
+
+Please have a look, and let us know if you're working on one of the items. It's
+best to open an issue to track your progress and to discuss any implementation
+questions you might have.
+
+Lastly, if you'd like something different to work on, please ping @purpleidea
+and I'll create an issue tailored especially for your approximate golang skill
+level and available time commitment in terms of hours you'd need to spend on the
+patch.
+
+Happy Hacking!
 
 ## Package resource
-- [ ] base resource [bug](https://github.com/purpleidea/mgmt/issues/11)
-- [ ] dnf blocker [bug](https://github.com/hughsie/PackageKit/issues/110)
-- [ ] install signal blocker [bug](https://github.com/hughsie/PackageKit/issues/109)
 
-## File resource [bug](https://github.com/purpleidea/mgmt/issues/13) [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
-- [ ] ability to make/delete folders
-- [ ] recursive argument (can recursively watch/modify contents)
-- [ ] force argument (can cause switch from file <-> folder)
+- [ ] getfiles support on debian [bug](https://github.com/hughsie/PackageKit/issues/118)
+- [ ] directory info on fedora [bug](https://github.com/hughsie/PackageKit/issues/117)
+- [ ] dnf blocker [bug](https://github.com/hughsie/PackageKit/issues/110)
+
+## File resource [bug](https://github.com/purpleidea/mgmt/issues/64) [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
+
+- [ ] recurse limit support [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
 - [ ] fanotify support [bug](https://github.com/go-fsnotify/fsnotify/issues/114)
 
+## Svc resource
+
+- [ ] refreshonly support [:heart:](https://github.com/purpleidea/mgmt/issues/464)
+
 ## Exec resource
+
 - [ ] base resource improvements
 
 ## Timer resource
-- [ ] base resource [bug](https://github.com/purpleidea/mgmt/issues/15) [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
-- [ ] reset on recompile
-- [ ] increment algorithm (linear, exponential, etc...)
+
+- [ ] increment algorithm (linear, exponential, etc...) [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
+
+## User/Group resource
+
+- [ ] automatic edges to file resource [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
+
+## Http resource
+
+- [ ] base resource [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
 
 ## Etcd improvements
-- [ ] embedded etcd master
-- [ ] capnslog fixes [bug](https://github.com/coreos/etcd/issues/4115)
+
+- [ ] fix etcd race bug that only happens during CI testing (intermittently
+failing test case issue)
+
+## Torrent/dht file transfer
+
+- [ ] base plumbing
+
+## GPG/Auth improvements
+
+- [ ] base plumbing
+
+## Resource improvements
+
+- [ ] more reversible resources implemented
+- [ ] more "cloud" resources
 
 ## Language improvements
-- [ ] language design
-- [ ] lexer/parser
+
+- [ ] more core functions
 - [ ] automatic language formatter, ala `gofmt`
 - [ ] gedit/gnome-builder/gtksourceview syntax highlighting
 - [ ] vim syntax highlighting
-- [ ] emacs syntax highlighting
+- [ ] emacs syntax highlighting: see `misc/emacs/` (needs updating)
+- [ ] exposed $error variable for feedback in the language
+- [ ] improve the printf function to add %[]s, %[]f ([]str, []float) and map,
+struct, nested etc... %v would be nice too!
+- [ ] add line/col/file annotations to AST so we can get locations of errors
+that the parser finds
+- [ ] add more error messages with the `%error` pattern in parser.y
+- [ ] we should have helper functions or language sugar to pull a field out of a
+struct, or a value out of a map, or an index out of a list, etc...
+
+## Engine improvements
+
+- [ ] add a "waiting for func" message in the func engine to notify the user
+about slow functions...
 
 ## Other
-- [ ] better error/retry handling
-- [ ] resource grouping
-- [ ] automatic dependency adding (eg: packagekit file dependencies)
-- [ ] mgmt systemd service file [bug](https://github.com/purpleidea/mgmt/issues/12) [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
-- [ ] deb package target in Makefile
+
 - [ ] reproducible builds
 - [ ] add your suggestions!

Vagrantfile

@@ -0,0 +1,51 @@
+Vagrant.configure(2) do |config|
+	config.ssh.forward_agent = true
+	config.ssh.username = 'vagrant'
+	config.vm.network "private_network", ip: "192.168.219.2"
+
+	config.vm.synced_folder ".", "/vagrant", disabled: true
+
+	config.vm.define "mgmt-dev" do |instance|
+		instance.vm.box = "bento/fedora-31"
+	end
+
+	config.vm.provider "virtualbox" do |v|
+		v.memory = 1536
+		v.cpus = 2
+	end
+	config.vm.provider "libvirt" do |v|
+		v.memory = 2048
+	end
+
+	config.vm.provision "file", source: "vagrant/motd", destination: ".motd"
+	config.vm.provision "shell", inline: "cp ~vagrant/.motd /etc/motd"
+
+	config.vm.provision "file", source: "vagrant/mgmt.bashrc", destination: ".mgmt.bashrc"
+	config.vm.provision "file", source: "~/.gitconfig", destination: ".gitconfig"
+
+	config.vm.provision "shell", inline: "dnf install -y golang git make"
+
+	# set up packagekit
+	config.vm.provision "shell" do |shell|
+		shell.inline = <<-SCRIPT
+			dnf install -y PackageKit
+			systemctl enable packagekit
+			systemctl start packagekit
+		SCRIPT
+	end
+
+	# set up vagrant home
+	script = <<-SCRIPT
+		grep -q 'mgmt\.bashrc' ~/.bashrc || echo '. ~/.mgmt.bashrc' >>~/.bashrc
+		. ~/.mgmt.bashrc
+		mkdir -p ~/gopath/src/github.com/purpleidea
+		cd ~/gopath/src/github.com/purpleidea
+		git clone https://github.com/purpleidea/mgmt --recursive
+		cd mgmt
+		make deps
+	SCRIPT
+	config.vm.provision "shell" do |shell|
+		shell.privileged = false
+		shell.inline = script
+	end
+end

art/.gitignore

@@ -0,0 +1,2 @@
+*.png
+misc/

art/mgmt_logo_default_symbol.svg

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 120 107.1" style="enable-background:new 0 0 120 107.1;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#FFFFFF;}
+	.st1{fill:#E22434;}
+	.st2{display:none;}
+	.st3{fill:#1B3663;}
+	.st4{fill:#00B1D1;}
+	.st5{fill:#BFE6EF;}
+	.st6{fill:#69CBE0;}
+	.st7{fill:#0080BD;}
+	.st8{fill:#005DAB;}
+	.st9{fill:#183660;}
+	.st10{fill:none;stroke:#183660;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st11{fill:none;stroke:#183660;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st12{fill:none;stroke:#183660;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st13{fill:none;stroke:#C0E6EF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st14{fill:#C0E6EF;}
+	.st15{fill:none;stroke:#C0E6EF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st16{fill:none;stroke:#C0E6EF;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st17{fill:none;stroke:#FFFFFF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st18{fill:none;stroke:#FFFFFF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st19{fill:none;stroke:#FFFFFF;stroke-width:1.6201;stroke-miterlimit:10;}
+</style>
+<g id="Layer_2">
+</g>
+<g id="Layer_1">
+	<g>
+		<g>
+			<g>
+				<line class="st10" x1="29.2" y1="24.1" x2="52.1" y2="42.8"/>
+				<g>
+					<polygon class="st9" points="27.7,27.8 24.9,20.5 32.6,21.8 					"/>
+				</g>
+			</g>
+		</g>
+		<circle class="st5" cx="16.1" cy="12.2" r="12.1"/>
+		<g>
+			<g>
+				<line class="st10" x1="52.1" y1="42.1" x2="74.1" y2="80"/>
+				<g>
+					<polygon class="st9" points="70.1,80.9 76.9,84.8 76.8,77.1 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st10" x1="69.4" y1="46.7" x2="95.8" y2="52.4"/>
+				<g>
+					<polygon class="st9" points="69.7,50.7 63.9,45.6 71.3,43.2 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st10" x1="52.1" y1="42.8" x2="71.9" y2="30.1"/>
+				<g>
+					<polygon class="st9" points="73.1,34 76.6,27.1 68.9,27.5 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st10" x1="16.8" y1="49.6" x2="34.8" y2="46.5"/>
+				<g>
+					<polygon class="st9" points="34.3,50.5 40.3,45.6 33,42.9 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st10" x1="92.3" y1="79.5" x2="107.8" y2="54.2"/>
+				<g>
+					<polygon class="st9" points="96.1,80.6 89.3,84.3 89.5,76.5 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st10" x1="97.3" y1="36.5" x2="107.8" y2="54.2"/>
+				<g>
+					<polygon class="st9" points="94.6,39.4 94.5,31.7 101.2,35.5 					"/>
+				</g>
+			</g>
+		</g>
+		<circle class="st3" cx="52.1" cy="42.8" r="12.1"/>
+		<circle class="st4" cx="12.2" cy="50.8" r="12.1"/>
+		<circle class="st7" cx="87.5" cy="21.7" r="12.1"/>
+		<circle class="st8" cx="83.5" cy="95" r="12.1"/>
+		<circle class="st6" cx="107.8" cy="54.2" r="12.1"/>
+	</g>
+</g>
+</svg>

art/mgmt_logo_default_tall.svg

@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 168.3 131.6" style="enable-background:new 0 0 168.3 131.6;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#FFFFFF;}
+	.st1{fill:#E22434;}
+	.st2{display:none;}
+	.st3{fill:#1B3663;}
+	.st4{fill:#00B1D1;}
+	.st5{fill:#BFE6EF;}
+	.st6{fill:#69CBE0;}
+	.st7{fill:#0080BD;}
+	.st8{fill:#005DAB;}
+	.st9{fill:#183660;}
+	.st10{fill:none;stroke:#183660;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st11{fill:none;stroke:#183660;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st12{fill:none;stroke:#183660;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st13{fill:none;stroke:#C0E6EF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st14{fill:#C0E6EF;}
+	.st15{fill:none;stroke:#C0E6EF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st16{fill:none;stroke:#C0E6EF;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st17{fill:none;stroke:#FFFFFF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st18{fill:none;stroke:#FFFFFF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st19{fill:none;stroke:#FFFFFF;stroke-width:1.6201;stroke-miterlimit:10;}
+</style>
+<g id="Layer_2">
+</g>
+<g id="Layer_1">
+	<g>
+		<g>
+			<g>
+				<path class="st3" d="M4.7,105l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9V124h-5v-12.1c0-1.1-0.2-1.9-0.5-2.4c-0.3-0.5-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6V124H9v-12.1
+					c0-1.1-0.1-1.9-0.4-2.4c-0.3-0.5-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4V124H0v-19H4.7z"/>
+				<path class="st3" d="M26.4,113.9c0-3.1,0.6-5.4,1.7-7s2.7-2.3,4.7-2.3c1.7,0,3.1,0.7,4,2L37,105h4.5v19c0,2.4-0.7,4.3-2,5.6
+					c-1.4,1.3-3.3,1.9-5.9,1.9c-1,0-2.1-0.2-3.3-0.6s-2-0.9-2.6-1.6l1.7-3.4c0.5,0.5,1.1,0.9,1.8,1.2c0.7,0.3,1.5,0.5,2.1,0.5
+					c1.1,0,1.9-0.3,2.4-0.8s0.7-1.4,0.7-2.6v-1.6c-0.9,1.2-2.2,1.9-3.7,1.9c-2,0-3.6-0.8-4.7-2.4s-1.7-3.8-1.7-6.7V113.9z
+					 M31.4,115.2c0,1.8,0.2,3,0.7,3.8s1.2,1.2,2.2,1.2c1,0,1.8-0.4,2.3-1.1V110c-0.5-0.8-1.3-1.2-2.2-1.2c-1,0-1.7,0.4-2.2,1.2
+					s-0.7,2.1-0.7,3.9V115.2z"/>
+				<path class="st3" d="M50.1,105l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9V124h-5v-12.1c0-1.1-0.2-1.9-0.5-2.4s-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6V124h-5v-12.1
+					c0-1.1-0.1-1.9-0.4-2.4s-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4V124h-5v-19H50.1z"/>
+				<path class="st3" d="M78.2,100.3v4.7h2.5v3.7h-2.5v9.5c0,0.8,0.1,1.3,0.3,1.5c0.2,0.3,0.6,0.4,1.2,0.4c0.5,0,0.9,0,1.2-0.1
+					l0,3.9c-0.8,0.3-1.8,0.5-2.7,0.5c-3.2,0-4.8-1.8-4.9-5.5v-10.1h-2.2V105h2.2v-4.7H78.2z"/>
+				<path class="st4" d="M90.6,122.6c1.4,0,2.4-0.4,3.1-1.1c0.7-0.8,1.1-1.9,1.2-3.3h1.9c-0.1,1.9-0.7,3.5-1.9,4.6
+					c-1.1,1.1-2.6,1.7-4.3,1.7c-2.3,0-4-0.7-5.1-2.2s-1.7-3.6-1.8-6.4v-2.3c0-2.9,0.6-5.1,1.7-6.6s2.9-2.2,5.1-2.2
+					c1.9,0,3.4,0.6,4.5,1.8s1.7,2.9,1.7,5H95c-0.1-1.6-0.5-2.8-1.2-3.6s-1.8-1.3-3.1-1.3c-1.7,0-2.9,0.6-3.7,1.7s-1.2,2.9-1.2,5.2
+					v2.2c0,2.4,0.4,4.2,1.2,5.3S89,122.6,90.6,122.6z"/>
+				<path class="st4" d="M100.5,113.6c0-2.7,0.6-4.9,1.9-6.5s2.9-2.4,5.1-2.4c2.2,0,3.9,0.8,5.1,2.4s1.9,3.7,1.9,6.5v2
+					c0,2.8-0.6,5-1.9,6.5s-2.9,2.3-5.1,2.3c-2.1,0-3.8-0.8-5-2.3s-1.9-3.6-1.9-6.3V113.6z M102.5,115.5c0,2.2,0.4,3.9,1.3,5.2
+					c0.9,1.3,2.1,1.9,3.7,1.9c1.6,0,2.8-0.6,3.7-1.8s1.3-2.9,1.3-5.2v-2c0-2.2-0.4-3.9-1.3-5.2c-0.9-1.3-2.1-1.9-3.7-1.9
+					c-1.5,0-2.7,0.6-3.6,1.8s-1.3,2.9-1.4,5.1V115.5z"/>
+				<path class="st4" d="M121.1,105l0.1,3c0.6-1,1.3-1.9,2.2-2.5s1.9-0.9,3-0.9c3.3,0,5,2.2,5.1,6.6V124h-1.9v-12.5
+					c0-1.7-0.3-3-0.9-3.8c-0.6-0.8-1.5-1.2-2.8-1.2c-1,0-1.9,0.4-2.8,1.2s-1.4,1.8-1.9,3.2V124h-2v-19H121.1z"/>
+				<path class="st4" d="M138.2,124v-17.3h-2.6V105h2.6v-2.5c0-1.9,0.5-3.3,1.3-4.3s2-1.5,3.5-1.5c0.7,0,1.3,0.1,1.9,0.3l-0.1,1.8
+					c-0.5-0.1-1-0.2-1.6-0.2c-0.9,0-1.7,0.4-2.2,1.1s-0.8,1.7-0.8,3v2.3h3.7v1.8h-3.7V124H138.2z"/>
+				<path class="st4" d="M148,99.5c0-0.4,0.1-0.7,0.3-1s0.5-0.4,0.9-0.4s0.7,0.1,1,0.4s0.3,0.6,0.3,1s-0.1,0.7-0.3,1s-0.5,0.4-1,0.4
+					s-0.7-0.1-0.9-0.4S148,99.9,148,99.5z M150.2,124h-2v-19h2V124z"/>
+				<path class="st4" d="M155.3,113.6c0-3,0.5-5.2,1.5-6.7s2.6-2.2,4.6-2.2c2.2,0,3.8,1,4.9,3l0.1-2.7h1.8v19.6c0,2.3-0.6,4-1.6,5.2
+					c-1.1,1.2-2.7,1.8-4.7,1.8c-1,0-2.1-0.3-3.2-0.8s-1.9-1.1-2.4-1.9l0.9-1.4c1.3,1.5,2.8,2.2,4.5,2.2c1.6,0,2.7-0.4,3.5-1.3
+					c0.7-0.8,1.1-2.1,1.1-3.8v-3c-1.1,1.8-2.7,2.7-4.9,2.7c-2,0-3.5-0.7-4.5-2.2s-1.6-3.6-1.6-6.5V113.6z M157.2,115.4
+					c0,2.4,0.4,4.2,1.1,5.4s1.9,1.7,3.5,1.7c2.1,0,3.6-1,4.5-3v-9.7c-0.9-2.2-2.4-3.3-4.4-3.3c-1.6,0-2.8,0.6-3.5,1.7
+					s-1.1,2.9-1.1,5.3V115.4z"/>
+			</g>
+		</g>
+		<g>
+			<g>
+				<g>
+					<line class="st11" x1="58.9" y1="20.1" x2="77.9" y2="35.6"/>
+					<g>
+						<polygon class="st9" points="57.6,23.2 55.3,17.1 61.7,18.2 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st5" cx="48" cy="10.1" r="10.1"/>
+			<g>
+				<g>
+					<line class="st11" x1="77.9" y1="35.1" x2="96.2" y2="66.7"/>
+					<g>
+						<polygon class="st9" points="93,67.5 98.6,70.7 98.6,64.2 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st11" x1="92.3" y1="38.9" x2="114.4" y2="43.6"/>
+					<g>
+						<polygon class="st9" points="92.6,42.3 87.8,38 93.9,36 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st11" x1="77.9" y1="35.6" x2="94.5" y2="25.1"/>
+					<g>
+						<polygon class="st9" points="95.4,28.3 98.4,22.6 91.9,22.9 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st11" x1="48.5" y1="41.3" x2="63.5" y2="38.7"/>
+					<g>
+						<polygon class="st9" points="63.1,42.1 68.1,38 62,35.7 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st11" x1="111.4" y1="66.3" x2="124.4" y2="45.2"/>
+					<g>
+						<polygon class="st9" points="114.6,67.2 109,70.2 109.1,63.8 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st11" x1="115.6" y1="30.4" x2="124.4" y2="45.2"/>
+					<g>
+						<polygon class="st9" points="113.3,32.8 113.3,26.4 118.9,29.5 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st3" cx="77.9" cy="35.6" r="10.1"/>
+			<circle class="st4" cx="44.6" cy="42.4" r="10.1"/>
+			<circle class="st7" cx="107.4" cy="18.1" r="10.1"/>
+			<circle class="st8" cx="104.1" cy="79.1" r="10.1"/>
+			<circle class="st6" cx="124.4" cy="45.2" r="10.1"/>
+		</g>
+	</g>
+</g>
+</svg>

art/mgmt_logo_default_wide.svg

@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 260.4 71.4" style="enable-background:new 0 0 260.4 71.4;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#FFFFFF;}
+	.st1{fill:#E22434;}
+	.st2{display:none;}
+	.st3{fill:#1B3663;}
+	.st4{fill:#00B1D1;}
+	.st5{fill:#BFE6EF;}
+	.st6{fill:#69CBE0;}
+	.st7{fill:#0080BD;}
+	.st8{fill:#005DAB;}
+	.st9{fill:#183660;}
+	.st10{fill:none;stroke:#183660;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st11{fill:none;stroke:#183660;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st12{fill:none;stroke:#183660;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st13{fill:none;stroke:#C0E6EF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st14{fill:#C0E6EF;}
+	.st15{fill:none;stroke:#C0E6EF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st16{fill:none;stroke:#C0E6EF;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st17{fill:none;stroke:#FFFFFF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st18{fill:none;stroke:#FFFFFF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st19{fill:none;stroke:#FFFFFF;stroke-width:1.6201;stroke-miterlimit:10;}
+</style>
+<g id="Layer_2">
+</g>
+<g id="Layer_1">
+	<g>
+		<g>
+			<g>
+				<path class="st3" d="M96.7,25.7l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9v12.5h-5V32.6c0-1.1-0.2-1.9-0.5-2.4s-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6v12.9h-5V32.6
+					c0-1.1-0.1-1.9-0.4-2.4s-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4v13.8h-5v-19H96.7z"/>
+				<path class="st3" d="M118.5,34.6c0-3.1,0.6-5.4,1.7-7s2.7-2.3,4.7-2.3c1.7,0,3.1,0.7,4,2l0.2-1.7h4.5v19c0,2.4-0.7,4.3-2,5.6
+					c-1.4,1.3-3.3,1.9-5.9,1.9c-1,0-2.1-0.2-3.3-0.6s-2-0.9-2.6-1.6l1.7-3.4c0.5,0.5,1.1,0.9,1.8,1.2c0.7,0.3,1.5,0.5,2.1,0.5
+					c1.1,0,1.9-0.3,2.4-0.8s0.7-1.4,0.7-2.6v-1.6c-0.9,1.2-2.2,1.9-3.7,1.9c-2,0-3.6-0.8-4.7-2.4s-1.7-3.8-1.7-6.7V34.6z
+					 M123.5,35.9c0,1.8,0.2,3,0.7,3.8s1.2,1.2,2.2,1.2c1,0,1.8-0.4,2.3-1.1v-9.1c-0.5-0.8-1.3-1.2-2.2-1.2c-1,0-1.7,0.4-2.2,1.2
+					s-0.7,2.1-0.7,3.9V35.9z"/>
+				<path class="st3" d="M142.2,25.7l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9v12.5h-5V32.6c0-1.1-0.2-1.9-0.5-2.4c-0.3-0.5-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6v12.9h-5V32.6
+					c0-1.1-0.1-1.9-0.4-2.4c-0.3-0.5-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4v13.8h-5v-19H142.2z"/>
+				<path class="st3" d="M170.3,21v4.7h2.5v3.7h-2.5v9.5c0,0.8,0.1,1.3,0.3,1.5c0.2,0.3,0.6,0.4,1.2,0.4c0.5,0,0.9,0,1.2-0.1l0,3.9
+					c-0.8,0.3-1.8,0.5-2.7,0.5c-3.2,0-4.8-1.8-4.9-5.5V29.4h-2.2v-3.7h2.2V21H170.3z"/>
+				<path class="st4" d="M182.7,43.2c1.4,0,2.4-0.4,3.1-1.1s1.1-1.8,1.2-3.3h1.9c-0.1,1.9-0.7,3.5-1.9,4.6s-2.6,1.7-4.3,1.7
+					c-2.3,0-4-0.7-5.1-2.2s-1.7-3.6-1.8-6.4v-2.3c0-2.9,0.6-5.1,1.7-6.6s2.9-2.2,5.1-2.2c1.9,0,3.4,0.6,4.5,1.8s1.7,2.9,1.7,5H187
+					c-0.1-1.6-0.5-2.8-1.2-3.6s-1.8-1.3-3.1-1.3c-1.7,0-2.9,0.6-3.7,1.7c-0.8,1.1-1.2,2.9-1.2,5.2v2.2c0,2.4,0.4,4.2,1.2,5.3
+					S181,43.2,182.7,43.2z"/>
+				<path class="st4" d="M192.6,34.2c0-2.7,0.6-4.9,1.9-6.5s2.9-2.4,5.1-2.4c2.2,0,3.9,0.8,5.1,2.4c1.2,1.6,1.9,3.7,1.9,6.5v2
+					c0,2.8-0.6,5-1.9,6.5s-2.9,2.3-5.1,2.3s-3.8-0.8-5-2.3s-1.9-3.6-1.9-6.3V34.2z M194.6,36.2c0,2.2,0.4,3.9,1.3,5.2
+					c0.9,1.3,2.1,1.9,3.7,1.9c1.6,0,2.8-0.6,3.7-1.8c0.8-1.2,1.3-2.9,1.3-5.2v-2c0-2.2-0.4-3.9-1.3-5.2c-0.9-1.3-2.1-1.9-3.7-1.9
+					c-1.5,0-2.7,0.6-3.6,1.8c-0.9,1.2-1.3,2.9-1.4,5.1V36.2z"/>
+				<path class="st4" d="M213.2,25.7l0.1,3c0.6-1,1.3-1.9,2.2-2.5s1.9-0.9,3-0.9c3.3,0,5,2.2,5.1,6.6v12.7h-1.9V32.2
+					c0-1.7-0.3-3-0.9-3.8c-0.6-0.8-1.5-1.2-2.8-1.2c-1,0-1.9,0.4-2.8,1.2s-1.4,1.8-1.9,3.2v13.2h-2v-19H213.2z"/>
+				<path class="st4" d="M230.3,44.7V27.4h-2.6v-1.8h2.6v-2.5c0-1.9,0.5-3.3,1.3-4.3s2-1.5,3.5-1.5c0.7,0,1.3,0.1,1.9,0.3l-0.1,1.8
+					c-0.5-0.1-1-0.2-1.6-0.2c-0.9,0-1.7,0.4-2.2,1.1s-0.8,1.7-0.8,3v2.3h3.7v1.8h-3.7v17.3H230.3z"/>
+				<path class="st4" d="M240.1,20.2c0-0.4,0.1-0.7,0.3-1s0.5-0.4,0.9-0.4s0.7,0.1,1,0.4s0.3,0.6,0.3,1s-0.1,0.7-0.3,1
+					s-0.5,0.4-1,0.4s-0.7-0.1-0.9-0.4S240.1,20.6,240.1,20.2z M242.3,44.7h-2v-19h2V44.7z"/>
+				<path class="st4" d="M247.4,34.3c0-3,0.5-5.2,1.5-6.7s2.6-2.2,4.6-2.2c2.2,0,3.8,1,4.9,3l0.1-2.7h1.8v19.6c0,2.3-0.6,4-1.6,5.2
+					s-2.7,1.8-4.7,1.8c-1,0-2.1-0.3-3.2-0.8s-1.9-1.1-2.4-1.9l0.9-1.4c1.3,1.5,2.8,2.2,4.5,2.2c1.6,0,2.7-0.4,3.5-1.3
+					c0.7-0.8,1.1-2.1,1.1-3.8v-3c-1.1,1.8-2.7,2.7-4.9,2.7c-2,0-3.5-0.7-4.5-2.2s-1.6-3.6-1.6-6.5V34.3z M249.3,36.1
+					c0,2.4,0.4,4.2,1.1,5.4s1.9,1.7,3.5,1.7c2.1,0,3.6-1,4.5-3v-9.7c-0.9-2.2-2.4-3.3-4.4-3.3c-1.6,0-2.8,0.6-3.5,1.7
+					s-1.1,2.9-1.1,5.3V36.1z"/>
+			</g>
+		</g>
+		<g>
+			<g>
+				<g>
+					<line class="st12" x1="19.5" y1="16" x2="34.7" y2="28.5"/>
+					<g>
+						<polygon class="st9" points="18.4,18.5 16.6,13.7 21.7,14.5 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st5" cx="10.8" cy="8.1" r="8.1"/>
+			<g>
+				<g>
+					<line class="st12" x1="34.7" y1="28" x2="49.4" y2="53.3"/>
+					<g>
+						<polygon class="st9" points="46.8,54 51.2,56.5 51.2,51.4 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st12" x1="46.2" y1="31.1" x2="63.9" y2="34.9"/>
+					<g>
+						<polygon class="st9" points="46.4,33.8 42.6,30.4 47.5,28.8 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st12" x1="34.7" y1="28.5" x2="47.9" y2="20.1"/>
+					<g>
+						<polygon class="st9" points="48.7,22.7 51.1,18.1 45.9,18.3 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st12" x1="11.2" y1="33.1" x2="23.2" y2="31"/>
+					<g>
+						<polygon class="st9" points="22.9,33.7 26.8,30.4 22,28.6 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st12" x1="61.5" y1="53" x2="71.9" y2="36.1"/>
+					<g>
+						<polygon class="st9" points="64.1,53.7 59.5,56.2 59.7,51 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st12" x1="64.2" y1="24.2" x2="70.7" y2="33.9"/>
+					<g>
+						<polygon class="st9" points="62.5,26.3 62.2,21.1 66.8,23.4 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st3" cx="34.7" cy="28.5" r="8.1"/>
+			<circle class="st4" cx="8.1" cy="33.9" r="8.1"/>
+			<circle class="st7" cx="58.3" cy="14.5" r="8.1"/>
+			<circle class="st8" cx="55.7" cy="63.3" r="8.1"/>
+			<circle class="st6" cx="71.9" cy="36.1" r="8.1"/>
+		</g>
+	</g>
+</g>
+</svg>

art/mgmt_logo_reversed_symbol.svg

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 120 107.1" style="enable-background:new 0 0 120 107.1;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#FFFFFF;}
+	.st1{fill:#E22434;}
+	.st2{display:none;}
+	.st3{fill:#1B3663;}
+	.st4{fill:#00B1D1;}
+	.st5{fill:#BFE6EF;}
+	.st6{fill:#69CBE0;}
+	.st7{fill:#0080BD;}
+	.st8{fill:#005DAB;}
+	.st9{fill:#183660;}
+	.st10{fill:none;stroke:#183660;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st11{fill:none;stroke:#183660;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st12{fill:none;stroke:#183660;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st13{fill:none;stroke:#C0E6EF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st14{fill:#C0E6EF;}
+	.st15{fill:none;stroke:#C0E6EF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st16{fill:none;stroke:#C0E6EF;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st17{fill:none;stroke:#FFFFFF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st18{fill:none;stroke:#FFFFFF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st19{fill:none;stroke:#FFFFFF;stroke-width:1.6201;stroke-miterlimit:10;}
+</style>
+<g id="Layer_2">
+</g>
+<g id="Layer_1">
+	<g>
+		<g>
+			<g>
+				<line class="st13" x1="29.2" y1="24.1" x2="52.1" y2="42.8"/>
+				<g>
+					<polygon class="st14" points="27.7,27.8 24.9,20.5 32.6,21.8 					"/>
+				</g>
+			</g>
+		</g>
+		<circle class="st3" cx="16.1" cy="12.2" r="12.1"/>
+		<g>
+			<g>
+				<line class="st13" x1="52.1" y1="42.1" x2="74.1" y2="80"/>
+				<g>
+					<polygon class="st14" points="70.1,80.9 76.9,84.8 76.8,77.1 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st13" x1="69.4" y1="46.7" x2="95.8" y2="52.4"/>
+				<g>
+					<polygon class="st14" points="69.7,50.7 63.9,45.6 71.3,43.2 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st13" x1="52.1" y1="42.8" x2="71.9" y2="30.1"/>
+				<g>
+					<polygon class="st14" points="73.1,34 76.6,27.1 68.9,27.5 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st13" x1="16.8" y1="49.6" x2="34.8" y2="46.5"/>
+				<g>
+					<polygon class="st14" points="34.3,50.5 40.3,45.6 33,42.9 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st13" x1="92.3" y1="79.5" x2="107.8" y2="54.2"/>
+				<g>
+					<polygon class="st14" points="96.1,80.6 89.3,84.3 89.5,76.5 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st13" x1="97.2" y1="36.3" x2="107.8" y2="54.2"/>
+				<g>
+					<polygon class="st14" points="94.4,39.3 94.3,31.5 101.1,35.3 					"/>
+				</g>
+			</g>
+		</g>
+		<circle class="st5" cx="52.1" cy="42.8" r="12.1"/>
+		<circle class="st4" cx="12.2" cy="50.8" r="12.1"/>
+		<circle class="st7" cx="87.5" cy="21.7" r="12.1"/>
+		<circle class="st8" cx="83.5" cy="95" r="12.1"/>
+		<circle class="st6" cx="107.8" cy="54.2" r="12.1"/>
+	</g>
+</g>
+</svg>

art/mgmt_logo_reversed_tall.svg

@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 168.3 133" style="enable-background:new 0 0 168.3 133;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#FFFFFF;}
+	.st1{fill:#E22434;}
+	.st2{display:none;}
+	.st3{fill:#1B3663;}
+	.st4{fill:#00B1D1;}
+	.st5{fill:#BFE6EF;}
+	.st6{fill:#69CBE0;}
+	.st7{fill:#0080BD;}
+	.st8{fill:#005DAB;}
+	.st9{fill:#183660;}
+	.st10{fill:none;stroke:#183660;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st11{fill:none;stroke:#183660;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st12{fill:none;stroke:#183660;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st13{fill:none;stroke:#C0E6EF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st14{fill:#C0E6EF;}
+	.st15{fill:none;stroke:#C0E6EF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st16{fill:none;stroke:#C0E6EF;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st17{fill:none;stroke:#FFFFFF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st18{fill:none;stroke:#FFFFFF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st19{fill:none;stroke:#FFFFFF;stroke-width:1.6201;stroke-miterlimit:10;}
+</style>
+<g id="Layer_2">
+</g>
+<g id="Layer_1">
+	<g>
+		<g>
+			<g>
+				<path class="st0" d="M4.7,106.4l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9v12.5h-5v-12.1c0-1.1-0.2-1.9-0.5-2.4c-0.3-0.5-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6v12.9H9v-12.1
+					c0-1.1-0.1-1.9-0.4-2.4c-0.3-0.5-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4v13.8H0v-19H4.7z"/>
+				<path class="st0" d="M26.4,115.3c0-3.1,0.6-5.4,1.7-7s2.7-2.3,4.7-2.3c1.7,0,3.1,0.7,4,2l0.2-1.7h4.5v19c0,2.4-0.7,4.3-2,5.6
+					c-1.4,1.3-3.3,1.9-5.9,1.9c-1,0-2.1-0.2-3.3-0.6s-2-0.9-2.6-1.6l1.7-3.4c0.5,0.5,1.1,0.9,1.8,1.2c0.7,0.3,1.5,0.5,2.1,0.5
+					c1.1,0,1.9-0.3,2.4-0.8c0.5-0.5,0.7-1.4,0.7-2.6v-1.6c-0.9,1.2-2.2,1.9-3.7,1.9c-2,0-3.6-0.8-4.7-2.4s-1.7-3.8-1.7-6.7V115.3z
+					 M31.4,116.6c0,1.8,0.2,3,0.7,3.8s1.2,1.2,2.2,1.2c1,0,1.8-0.4,2.3-1.1v-9.1c-0.5-0.8-1.3-1.2-2.2-1.2c-1,0-1.7,0.4-2.2,1.2
+					s-0.7,2.1-0.7,3.9V116.6z"/>
+				<path class="st0" d="M50.1,106.4l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9v12.5h-5v-12.1c0-1.1-0.2-1.9-0.5-2.4s-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6v12.9h-5v-12.1
+					c0-1.1-0.1-1.9-0.4-2.4s-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4v13.8h-5v-19H50.1z"/>
+				<path class="st0" d="M78.2,101.7v4.7h2.5v3.7h-2.5v9.5c0,0.8,0.1,1.3,0.3,1.5c0.2,0.3,0.6,0.4,1.2,0.4c0.5,0,0.9,0,1.2-0.1
+					l0,3.9c-0.8,0.3-1.8,0.5-2.7,0.5c-3.2,0-4.8-1.8-4.9-5.5v-10.1h-2.2v-3.7h2.2v-4.7H78.2z"/>
+				<path class="st4" d="M90.6,124c1.4,0,2.4-0.4,3.1-1.1c0.7-0.8,1.1-1.9,1.2-3.3h1.9c-0.1,1.9-0.7,3.5-1.9,4.6
+					c-1.1,1.1-2.6,1.7-4.3,1.7c-2.3,0-4-0.7-5.1-2.2s-1.7-3.6-1.8-6.4v-2.3c0-2.9,0.6-5.1,1.7-6.6s2.9-2.2,5.1-2.2
+					c1.9,0,3.4,0.6,4.5,1.8s1.7,2.9,1.7,5H95c-0.1-1.6-0.5-2.8-1.2-3.6s-1.8-1.3-3.1-1.3c-1.7,0-2.9,0.6-3.7,1.7s-1.2,2.9-1.2,5.2
+					v2.2c0,2.4,0.4,4.2,1.2,5.3S89,124,90.6,124z"/>
+				<path class="st4" d="M100.5,115c0-2.7,0.6-4.9,1.9-6.5s2.9-2.4,5.1-2.4c2.2,0,3.9,0.8,5.1,2.4s1.9,3.7,1.9,6.5v2
+					c0,2.8-0.6,5-1.9,6.5s-2.9,2.3-5.1,2.3c-2.1,0-3.8-0.8-5-2.3s-1.9-3.6-1.9-6.3V115z M102.5,116.9c0,2.2,0.4,3.9,1.3,5.2
+					c0.9,1.3,2.1,1.9,3.7,1.9c1.6,0,2.8-0.6,3.7-1.8s1.3-2.9,1.3-5.2v-2c0-2.2-0.4-3.9-1.3-5.2c-0.9-1.3-2.1-1.9-3.7-1.9
+					c-1.5,0-2.7,0.6-3.6,1.8s-1.3,2.9-1.4,5.1V116.9z"/>
+				<path class="st4" d="M121.1,106.4l0.1,3c0.6-1,1.3-1.9,2.2-2.5s1.9-0.9,3-0.9c3.3,0,5,2.2,5.1,6.6v12.7h-1.9v-12.5
+					c0-1.7-0.3-3-0.9-3.8c-0.6-0.8-1.5-1.2-2.8-1.2c-1,0-1.9,0.4-2.8,1.2s-1.4,1.8-1.9,3.2v13.2h-2v-19H121.1z"/>
+				<path class="st4" d="M138.2,125.4v-17.3h-2.6v-1.8h2.6v-2.5c0-1.9,0.5-3.3,1.3-4.3s2-1.5,3.5-1.5c0.7,0,1.3,0.1,1.9,0.3
+					l-0.1,1.8c-0.5-0.1-1-0.2-1.6-0.2c-0.9,0-1.7,0.4-2.2,1.1s-0.8,1.7-0.8,3v2.3h3.7v1.8h-3.7v17.3H138.2z"/>
+				<path class="st4" d="M148,100.9c0-0.4,0.1-0.7,0.3-1s0.5-0.4,0.9-0.4s0.7,0.1,1,0.4s0.3,0.6,0.3,1s-0.1,0.7-0.3,1
+					s-0.5,0.4-1,0.4s-0.7-0.1-0.9-0.4S148,101.3,148,100.9z M150.2,125.4h-2v-19h2V125.4z"/>
+				<path class="st4" d="M155.3,115c0-3,0.5-5.2,1.5-6.7s2.6-2.2,4.6-2.2c2.2,0,3.8,1,4.9,3l0.1-2.7h1.8V126c0,2.3-0.6,4-1.6,5.2
+					c-1.1,1.2-2.7,1.8-4.7,1.8c-1,0-2.1-0.3-3.2-0.8s-1.9-1.1-2.4-1.9l0.9-1.4c1.3,1.5,2.8,2.2,4.5,2.2c1.6,0,2.7-0.4,3.5-1.3
+					c0.7-0.8,1.1-2.1,1.1-3.8v-3c-1.1,1.8-2.7,2.7-4.9,2.7c-2,0-3.5-0.7-4.5-2.2s-1.6-3.6-1.6-6.5V115z M157.2,116.8
+					c0,2.4,0.4,4.2,1.1,5.4s1.9,1.7,3.5,1.7c2.1,0,3.6-1,4.5-3v-9.7c-0.9-2.2-2.4-3.3-4.4-3.3c-1.6,0-2.8,0.6-3.5,1.7
+					s-1.1,2.9-1.1,5.3V116.8z"/>
+			</g>
+		</g>
+		<g>
+			<g>
+				<g>
+					<line class="st16" x1="58.9" y1="20.1" x2="77.9" y2="35.6"/>
+					<g>
+						<polygon class="st14" points="57.6,23.2 55.3,17.1 61.7,18.2 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st3" cx="48" cy="10.1" r="10.1"/>
+			<g>
+				<g>
+					<line class="st16" x1="77.9" y1="35.1" x2="96.2" y2="66.7"/>
+					<g>
+						<polygon class="st14" points="93,67.5 98.6,70.7 98.6,64.2 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st16" x1="92.3" y1="38.9" x2="114.4" y2="43.6"/>
+					<g>
+						<polygon class="st14" points="92.6,42.3 87.8,38 93.9,36 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st16" x1="77.9" y1="35.6" x2="94.5" y2="25.1"/>
+					<g>
+						<polygon class="st14" points="95.4,28.3 98.4,22.6 91.9,22.9 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st16" x1="48.5" y1="41.3" x2="63.5" y2="38.7"/>
+					<g>
+						<polygon class="st14" points="63.1,42.1 68.1,38 62,35.7 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st16" x1="111.4" y1="66.3" x2="124.4" y2="45.2"/>
+					<g>
+						<polygon class="st14" points="114.6,67.2 109,70.2 109.1,63.8 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st16" x1="115.5" y1="30.5" x2="124.4" y2="45.2"/>
+					<g>
+						<polygon class="st14" points="113.2,32.9 113.1,26.5 118.8,29.6 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st5" cx="77.9" cy="35.6" r="10.1"/>
+			<circle class="st4" cx="44.6" cy="42.4" r="10.1"/>
+			<circle class="st7" cx="107.4" cy="18.1" r="10.1"/>
+			<circle class="st8" cx="104.1" cy="79.1" r="10.1"/>
+			<circle class="st6" cx="124.4" cy="45.2" r="10.1"/>
+		</g>
+	</g>
+</g>
+</svg>

art/mgmt_logo_reversed_wide.svg

@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 260.4 71.4" style="enable-background:new 0 0 260.4 71.4;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#FFFFFF;}
+	.st1{fill:#E22434;}
+	.st2{display:none;}
+	.st3{fill:#1B3663;}
+	.st4{fill:#00B1D1;}
+	.st5{fill:#BFE6EF;}
+	.st6{fill:#69CBE0;}
+	.st7{fill:#0080BD;}
+	.st8{fill:#005DAB;}
+	.st9{fill:#183660;}
+	.st10{fill:none;stroke:#183660;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st11{fill:none;stroke:#183660;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st12{fill:none;stroke:#183660;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st13{fill:none;stroke:#C0E6EF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st14{fill:#C0E6EF;}
+	.st15{fill:none;stroke:#C0E6EF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st16{fill:none;stroke:#C0E6EF;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st17{fill:none;stroke:#FFFFFF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st18{fill:none;stroke:#FFFFFF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st19{fill:none;stroke:#FFFFFF;stroke-width:1.6201;stroke-miterlimit:10;}
+</style>
+<g id="Layer_2">
+</g>
+<g id="Layer_1">
+	<g>
+		<g>
+			<g>
+				<path class="st0" d="M96.7,27.6l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9v12.5h-5V34.4c0-1.1-0.2-1.9-0.5-2.4c-0.3-0.5-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6v12.9h-5V34.5
+					c0-1.1-0.1-1.9-0.4-2.4c-0.3-0.5-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4v13.8h-5v-19H96.7z"/>
+				<path class="st0" d="M118.5,36.5c0-3.1,0.6-5.4,1.7-7s2.7-2.3,4.7-2.3c1.7,0,3.1,0.7,4,2l0.2-1.7h4.5v19c0,2.4-0.7,4.3-2,5.6
+					c-1.4,1.3-3.3,1.9-5.9,1.9c-1,0-2.1-0.2-3.3-0.6s-2-0.9-2.6-1.6l1.7-3.4c0.5,0.5,1.1,0.9,1.8,1.2c0.7,0.3,1.5,0.5,2.1,0.5
+					c1.1,0,1.9-0.3,2.4-0.8s0.7-1.4,0.7-2.6v-1.6c-0.9,1.2-2.2,1.9-3.7,1.9c-2,0-3.6-0.8-4.7-2.4s-1.7-3.8-1.7-6.7V36.5z
+					 M123.5,37.7c0,1.8,0.2,3,0.7,3.8s1.2,1.2,2.2,1.2c1,0,1.8-0.4,2.3-1.1v-9.1c-0.5-0.8-1.3-1.2-2.2-1.2c-1,0-1.7,0.4-2.2,1.2
+					c-0.5,0.8-0.7,2.1-0.7,3.9V37.7z"/>
+				<path class="st0" d="M142.2,27.6l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9v12.5h-5V34.4c0-1.1-0.2-1.9-0.5-2.4c-0.3-0.5-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6v12.9h-5V34.5
+					c0-1.1-0.1-1.9-0.4-2.4c-0.3-0.5-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4v13.8h-5v-19H142.2z"/>
+				<path class="st0" d="M170.3,22.9v4.7h2.5v3.7h-2.5v9.5c0,0.8,0.1,1.3,0.3,1.5c0.2,0.3,0.6,0.4,1.2,0.4c0.5,0,0.9,0,1.2-0.1
+					l0,3.9c-0.8,0.3-1.8,0.5-2.7,0.5c-3.2,0-4.8-1.8-4.9-5.5V31.3h-2.2v-3.7h2.2v-4.7H170.3z"/>
+				<path class="st4" d="M182.7,45.1c1.4,0,2.4-0.4,3.1-1.1c0.7-0.8,1.1-1.9,1.2-3.3h1.9c-0.1,1.9-0.7,3.5-1.9,4.6s-2.6,1.7-4.3,1.7
+					c-2.3,0-4-0.7-5.1-2.2s-1.7-3.6-1.8-6.4V36c0-2.9,0.6-5.1,1.7-6.6s2.9-2.2,5.1-2.2c1.9,0,3.4,0.6,4.5,1.8s1.7,2.9,1.7,5H187
+					c-0.1-1.6-0.5-2.8-1.2-3.6s-1.8-1.3-3.1-1.3c-1.7,0-2.9,0.6-3.7,1.7s-1.2,2.9-1.2,5.2v2.2c0,2.4,0.4,4.2,1.2,5.3
+					S181,45.1,182.7,45.1z"/>
+				<path class="st4" d="M192.6,36.1c0-2.7,0.6-4.9,1.9-6.5s2.9-2.4,5.1-2.4c2.2,0,3.9,0.8,5.1,2.4c1.2,1.6,1.9,3.7,1.9,6.5v2
+					c0,2.8-0.6,5-1.9,6.5s-2.9,2.3-5.1,2.3s-3.8-0.8-5-2.3s-1.9-3.6-1.9-6.3V36.1z M194.6,38.1c0,2.2,0.4,3.9,1.3,5.2
+					c0.9,1.3,2.1,1.9,3.7,1.9c1.6,0,2.8-0.6,3.7-1.8c0.8-1.2,1.3-2.9,1.3-5.2v-2c0-2.2-0.4-3.9-1.3-5.2c-0.9-1.3-2.1-1.9-3.7-1.9
+					c-1.5,0-2.7,0.6-3.6,1.8c-0.9,1.2-1.3,2.9-1.4,5.1V38.1z"/>
+				<path class="st4" d="M213.2,27.6l0.1,3c0.6-1,1.3-1.9,2.2-2.5s1.9-0.9,3-0.9c3.3,0,5,2.2,5.1,6.6v12.7h-1.9V34.1
+					c0-1.7-0.3-3-0.9-3.8c-0.6-0.8-1.5-1.2-2.8-1.2c-1,0-1.9,0.4-2.8,1.2s-1.4,1.8-1.9,3.2v13.2h-2v-19H213.2z"/>
+				<path class="st4" d="M230.3,46.6V29.3h-2.6v-1.8h2.6v-2.5c0-1.9,0.5-3.3,1.3-4.3s2-1.5,3.5-1.5c0.7,0,1.3,0.1,1.9,0.3l-0.1,1.8
+					c-0.5-0.1-1-0.2-1.6-0.2c-0.9,0-1.7,0.4-2.2,1.1s-0.8,1.7-0.8,3v2.3h3.7v1.8h-3.7v17.3H230.3z"/>
+				<path class="st4" d="M240.1,22.1c0-0.4,0.1-0.7,0.3-1s0.5-0.4,0.9-0.4s0.7,0.1,1,0.4s0.3,0.6,0.3,1s-0.1,0.7-0.3,1
+					s-0.5,0.4-1,0.4s-0.7-0.1-0.9-0.4S240.1,22.5,240.1,22.1z M242.3,46.6h-2v-19h2V46.6z"/>
+				<path class="st4" d="M247.4,36.2c0-3,0.5-5.2,1.5-6.7s2.6-2.2,4.6-2.2c2.2,0,3.8,1,4.9,3l0.1-2.7h1.8v19.6c0,2.3-0.6,4-1.6,5.2
+					s-2.7,1.8-4.7,1.8c-1,0-2.1-0.3-3.2-0.8s-1.9-1.1-2.4-1.9l0.9-1.4c1.3,1.5,2.8,2.2,4.5,2.2c1.6,0,2.7-0.4,3.5-1.3
+					c0.7-0.8,1.1-2.1,1.1-3.8v-3c-1.1,1.8-2.7,2.7-4.9,2.7c-2,0-3.5-0.7-4.5-2.2s-1.6-3.6-1.6-6.5V36.2z M249.3,38
+					c0,2.4,0.4,4.2,1.1,5.4s1.9,1.7,3.5,1.7c2.1,0,3.6-1,4.5-3v-9.7c-0.9-2.2-2.4-3.3-4.4-3.3c-1.6,0-2.8,0.6-3.5,1.7
+					s-1.1,2.9-1.1,5.3V38z"/>
+			</g>
+		</g>
+		<g>
+			<g>
+				<g>
+					<line class="st15" x1="19.5" y1="16" x2="34.7" y2="28.5"/>
+					<g>
+						<polygon class="st14" points="18.4,18.5 16.6,13.7 21.7,14.5 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st3" cx="10.8" cy="8.1" r="8.1"/>
+			<g>
+				<g>
+					<line class="st15" x1="34.7" y1="28" x2="49.4" y2="53.3"/>
+					<g>
+						<polygon class="st14" points="46.8,54 51.2,56.5 51.2,51.4 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st15" x1="46.2" y1="31.1" x2="63.9" y2="34.9"/>
+					<g>
+						<polygon class="st14" points="46.4,33.8 42.6,30.4 47.5,28.8 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st15" x1="34.7" y1="28.5" x2="47.9" y2="20.1"/>
+					<g>
+						<polygon class="st14" points="48.7,22.7 51.1,18.1 45.9,18.3 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st15" x1="11.2" y1="33.1" x2="23.2" y2="31"/>
+					<g>
+						<polygon class="st14" points="22.9,33.7 26.8,30.4 22,28.6 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st15" x1="61.5" y1="53" x2="71.9" y2="36.1"/>
+					<g>
+						<polygon class="st14" points="64.1,53.7 59.5,56.2 59.7,51 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st15" x1="64.8" y1="24.4" x2="71.9" y2="36.1"/>
+					<g>
+						<polygon class="st14" points="63,26.4 62.9,21.2 67.4,23.7 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st5" cx="34.7" cy="28.5" r="8.1"/>
+			<circle class="st4" cx="8.1" cy="33.9" r="8.1"/>
+			<circle class="st7" cx="58.3" cy="14.5" r="8.1"/>
+			<circle class="st8" cx="55.7" cy="63.3" r="8.1"/>
+			<circle class="st6" cx="71.9" cy="36.1" r="8.1"/>
+		</g>
+	</g>
+</g>
+</svg>

art/mgmt_logo_white_symbol.svg

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 120 107.1" style="enable-background:new 0 0 120 107.1;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#FFFFFF;}
+	.st1{fill:#E22434;}
+	.st2{display:none;}
+	.st3{fill:#1B3663;}
+	.st4{fill:#00B1D1;}
+	.st5{fill:#BFE6EF;}
+	.st6{fill:#69CBE0;}
+	.st7{fill:#0080BD;}
+	.st8{fill:#005DAB;}
+	.st9{fill:#183660;}
+	.st10{fill:none;stroke:#183660;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st11{fill:none;stroke:#183660;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st12{fill:none;stroke:#183660;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st13{fill:none;stroke:#C0E6EF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st14{fill:#C0E6EF;}
+	.st15{fill:none;stroke:#C0E6EF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st16{fill:none;stroke:#C0E6EF;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st17{fill:none;stroke:#FFFFFF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st18{fill:none;stroke:#FFFFFF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st19{fill:none;stroke:#FFFFFF;stroke-width:1.6201;stroke-miterlimit:10;}
+</style>
+<g id="Layer_2">
+</g>
+<g id="Layer_1">
+	<g>
+		<g>
+			<g>
+				<line class="st17" x1="29.2" y1="24.1" x2="52.1" y2="42.8"/>
+				<g>
+					<polygon class="st0" points="27.7,27.8 24.9,20.5 32.6,21.8 					"/>
+				</g>
+			</g>
+		</g>
+		<circle class="st0" cx="16.1" cy="12.2" r="12.1"/>
+		<g>
+			<g>
+				<line class="st17" x1="52.1" y1="42.1" x2="74.1" y2="80"/>
+				<g>
+					<polygon class="st0" points="70.1,80.9 76.9,84.8 76.8,77.1 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st17" x1="69.4" y1="46.7" x2="95.8" y2="52.4"/>
+				<g>
+					<polygon class="st0" points="69.7,50.7 63.9,45.6 71.3,43.2 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st17" x1="52.1" y1="42.8" x2="71.9" y2="30.1"/>
+				<g>
+					<polygon class="st0" points="73.1,34 76.6,27.1 68.9,27.5 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st17" x1="16.8" y1="49.6" x2="34.8" y2="46.5"/>
+				<g>
+					<polygon class="st0" points="34.3,50.5 40.3,45.6 33,42.9 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st17" x1="92.3" y1="79.5" x2="107.8" y2="54.2"/>
+				<g>
+					<polygon class="st0" points="96.1,80.6 89.3,84.3 89.5,76.5 					"/>
+				</g>
+			</g>
+		</g>
+		<g>
+			<g>
+				<line class="st17" x1="97.2" y1="36.6" x2="107.8" y2="54.2"/>
+				<g>
+					<polygon class="st0" points="94.4,39.5 94.3,31.8 101.1,35.5 					"/>
+				</g>
+			</g>
+		</g>
+		<circle class="st0" cx="52.1" cy="42.8" r="12.1"/>
+		<circle class="st0" cx="12.2" cy="50.8" r="12.1"/>
+		<circle class="st0" cx="87.5" cy="21.7" r="12.1"/>
+		<circle class="st0" cx="83.5" cy="95" r="12.1"/>
+		<circle class="st0" cx="107.8" cy="54.2" r="12.1"/>
+	</g>
+</g>
+</svg>

art/mgmt_logo_white_tall.svg

@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 168.3 131.4" style="enable-background:new 0 0 168.3 131.4;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#FFFFFF;}
+	.st1{fill:#E22434;}
+	.st2{display:none;}
+	.st3{fill:#1B3663;}
+	.st4{fill:#00B1D1;}
+	.st5{fill:#BFE6EF;}
+	.st6{fill:#69CBE0;}
+	.st7{fill:#0080BD;}
+	.st8{fill:#005DAB;}
+	.st9{fill:#183660;}
+	.st10{fill:none;stroke:#183660;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st11{fill:none;stroke:#183660;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st12{fill:none;stroke:#183660;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st13{fill:none;stroke:#C0E6EF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st14{fill:#C0E6EF;}
+	.st15{fill:none;stroke:#C0E6EF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st16{fill:none;stroke:#C0E6EF;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st17{fill:none;stroke:#FFFFFF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st18{fill:none;stroke:#FFFFFF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st19{fill:none;stroke:#FFFFFF;stroke-width:1.6201;stroke-miterlimit:10;}
+</style>
+<g id="Layer_2">
+</g>
+<g id="Layer_1">
+	<g>
+		<g>
+			<g>
+				<path class="st0" d="M4.7,104.8l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9v12.5h-5v-12.1c0-1.1-0.2-1.9-0.5-2.4c-0.3-0.5-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6v12.9H9v-12.1
+					c0-1.1-0.1-1.9-0.4-2.4c-0.3-0.5-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4v13.8H0v-19H4.7z"/>
+				<path class="st0" d="M26.4,113.8c0-3.1,0.6-5.4,1.7-7s2.7-2.3,4.7-2.3c1.7,0,3.1,0.7,4,2l0.2-1.7h4.5v19c0,2.4-0.7,4.3-2,5.6
+					c-1.4,1.3-3.3,1.9-5.9,1.9c-1,0-2.1-0.2-3.3-0.6s-2-0.9-2.6-1.6l1.7-3.4c0.5,0.5,1.1,0.9,1.8,1.2c0.7,0.3,1.5,0.5,2.1,0.5
+					c1.1,0,1.9-0.3,2.4-0.8s0.7-1.4,0.7-2.6v-1.6c-0.9,1.2-2.2,1.9-3.7,1.9c-2,0-3.6-0.8-4.7-2.4s-1.7-3.8-1.7-6.7V113.8z M31.4,115
+					c0,1.8,0.2,3,0.7,3.8s1.2,1.2,2.2,1.2c1,0,1.8-0.4,2.3-1.1v-9.1c-0.5-0.8-1.3-1.2-2.2-1.2c-1,0-1.7,0.4-2.2,1.2
+					s-0.7,2.1-0.7,3.9V115z"/>
+				<path class="st0" d="M50.1,104.8l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9v12.5h-5v-12.1c0-1.1-0.2-1.9-0.5-2.4s-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6v12.9h-5v-12.1
+					c0-1.1-0.1-1.9-0.4-2.4s-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4v13.8h-5v-19H50.1z"/>
+				<path class="st0" d="M78.2,100.2v4.7h2.5v3.7h-2.5v9.5c0,0.8,0.1,1.3,0.3,1.5c0.2,0.3,0.6,0.4,1.2,0.4c0.5,0,0.9,0,1.2-0.1
+					l0,3.9c-0.8,0.3-1.8,0.5-2.7,0.5c-3.2,0-4.8-1.8-4.9-5.5v-10.1h-2.2v-3.7h2.2v-4.7H78.2z"/>
+				<path class="st0" d="M90.6,122.4c1.4,0,2.4-0.4,3.1-1.1c0.7-0.8,1.1-1.8,1.2-3.3h1.9c-0.1,1.9-0.7,3.5-1.9,4.6
+					c-1.1,1.1-2.6,1.7-4.3,1.7c-2.3,0-4-0.7-5.1-2.2s-1.7-3.6-1.8-6.4v-2.3c0-2.9,0.6-5.1,1.7-6.6s2.9-2.2,5.1-2.2
+					c1.9,0,3.4,0.6,4.5,1.8s1.7,2.9,1.7,5H95c-0.1-1.6-0.5-2.8-1.2-3.6s-1.8-1.3-3.1-1.3c-1.7,0-2.9,0.6-3.7,1.7
+					c-0.8,1.1-1.2,2.9-1.2,5.2v2.2c0,2.4,0.4,4.2,1.2,5.3S89,122.4,90.6,122.4z"/>
+				<path class="st0" d="M100.5,113.4c0-2.7,0.6-4.9,1.9-6.5s2.9-2.4,5.1-2.4c2.2,0,3.9,0.8,5.1,2.4s1.9,3.7,1.9,6.5v2
+					c0,2.8-0.6,5-1.9,6.5s-2.9,2.3-5.1,2.3c-2.1,0-3.8-0.8-5-2.3s-1.9-3.6-1.9-6.3V113.4z M102.5,115.3c0,2.2,0.4,3.9,1.3,5.2
+					c0.9,1.3,2.1,1.9,3.7,1.9c1.6,0,2.8-0.6,3.7-1.8c0.8-1.2,1.3-2.9,1.3-5.2v-2c0-2.2-0.4-3.9-1.3-5.2c-0.9-1.3-2.1-1.9-3.7-1.9
+					c-1.5,0-2.7,0.6-3.6,1.8c-0.9,1.2-1.3,2.9-1.4,5.1V115.3z"/>
+				<path class="st0" d="M121.1,104.8l0.1,3c0.6-1,1.3-1.9,2.2-2.5s1.9-0.9,3-0.9c3.3,0,5,2.2,5.1,6.6v12.7h-1.9v-12.5
+					c0-1.7-0.3-3-0.9-3.8c-0.6-0.8-1.5-1.2-2.8-1.2c-1,0-1.9,0.4-2.8,1.2s-1.4,1.8-1.9,3.2v13.2h-2v-19H121.1z"/>
+				<path class="st0" d="M138.2,123.8v-17.3h-2.6v-1.8h2.6v-2.5c0-1.9,0.5-3.3,1.3-4.3s2-1.5,3.5-1.5c0.7,0,1.3,0.1,1.9,0.3
+					l-0.1,1.8c-0.5-0.1-1-0.2-1.6-0.2c-0.9,0-1.7,0.4-2.2,1.1s-0.8,1.7-0.8,3v2.3h3.7v1.8h-3.7v17.3H138.2z"/>
+				<path class="st0" d="M148,99.3c0-0.4,0.1-0.7,0.3-1s0.5-0.4,0.9-0.4s0.7,0.1,1,0.4s0.3,0.6,0.3,1s-0.1,0.7-0.3,1s-0.5,0.4-1,0.4
+					s-0.7-0.1-0.9-0.4S148,99.7,148,99.3z M150.2,123.8h-2v-19h2V123.8z"/>
+				<path class="st0" d="M155.3,113.5c0-3,0.5-5.2,1.5-6.7s2.6-2.2,4.6-2.2c2.2,0,3.8,1,4.9,3l0.1-2.7h1.8v19.6c0,2.3-0.6,4-1.6,5.2
+					c-1.1,1.2-2.7,1.8-4.7,1.8c-1,0-2.1-0.3-3.2-0.8s-1.9-1.1-2.4-1.9l0.9-1.4c1.3,1.5,2.8,2.2,4.5,2.2c1.6,0,2.7-0.4,3.5-1.3
+					c0.7-0.8,1.1-2.1,1.1-3.8v-3c-1.1,1.8-2.7,2.7-4.9,2.7c-2,0-3.5-0.7-4.5-2.2s-1.6-3.6-1.6-6.5V113.5z M157.2,115.2
+					c0,2.4,0.4,4.2,1.1,5.4s1.9,1.7,3.5,1.7c2.1,0,3.6-1,4.5-3v-9.7c-0.9-2.2-2.4-3.3-4.4-3.3c-1.6,0-2.8,0.6-3.5,1.7
+					s-1.1,2.9-1.1,5.3V115.2z"/>
+			</g>
+		</g>
+		<g>
+			<g>
+				<g>
+					<line class="st19" x1="58.9" y1="20.1" x2="77.9" y2="35.6"/>
+					<g>
+						<polygon class="st0" points="57.6,23.2 55.3,17.1 61.7,18.2 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st0" cx="48" cy="10.1" r="10.1"/>
+			<g>
+				<g>
+					<line class="st19" x1="77.9" y1="35.1" x2="96.2" y2="66.7"/>
+					<g>
+						<polygon class="st0" points="93,67.5 98.6,70.7 98.6,64.2 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st19" x1="92.3" y1="38.9" x2="114.4" y2="43.6"/>
+					<g>
+						<polygon class="st0" points="92.6,42.3 87.8,38 93.9,36 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st19" x1="77.9" y1="35.6" x2="94.5" y2="25.1"/>
+					<g>
+						<polygon class="st0" points="95.4,28.3 98.4,22.6 91.9,22.9 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st19" x1="48.5" y1="41.3" x2="63.5" y2="38.7"/>
+					<g>
+						<polygon class="st0" points="63.1,42.1 68.1,38 62,35.7 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st19" x1="111.4" y1="66.3" x2="124.4" y2="45.2"/>
+					<g>
+						<polygon class="st0" points="114.6,67.2 109,70.2 109.1,63.8 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st19" x1="115.4" y1="30.4" x2="124.4" y2="45.2"/>
+					<g>
+						<polygon class="st0" points="113.2,32.8 113,26.4 118.7,29.5 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st0" cx="77.9" cy="35.6" r="10.1"/>
+			<circle class="st0" cx="44.6" cy="42.4" r="10.1"/>
+			<circle class="st0" cx="107.4" cy="18.1" r="10.1"/>
+			<circle class="st0" cx="104.1" cy="79.1" r="10.1"/>
+			<circle class="st0" cx="124.4" cy="45.2" r="10.1"/>
+		</g>
+	</g>
+</g>
+</svg>

art/mgmt_logo_white_wide.svg

@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 260.4 71.4" style="enable-background:new 0 0 260.4 71.4;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#FFFFFF;}
+	.st1{fill:#E22434;}
+	.st2{display:none;}
+	.st3{fill:#1B3663;}
+	.st4{fill:#00B1D1;}
+	.st5{fill:#BFE6EF;}
+	.st6{fill:#69CBE0;}
+	.st7{fill:#0080BD;}
+	.st8{fill:#005DAB;}
+	.st9{fill:#183660;}
+	.st10{fill:none;stroke:#183660;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st11{fill:none;stroke:#183660;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st12{fill:none;stroke:#183660;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st13{fill:none;stroke:#C0E6EF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st14{fill:#C0E6EF;}
+	.st15{fill:none;stroke:#C0E6EF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st16{fill:none;stroke:#C0E6EF;stroke-width:1.6201;stroke-miterlimit:10;}
+	.st17{fill:none;stroke:#FFFFFF;stroke-width:1.9441;stroke-miterlimit:10;}
+	.st18{fill:none;stroke:#FFFFFF;stroke-width:1.2961;stroke-miterlimit:10;}
+	.st19{fill:none;stroke:#FFFFFF;stroke-width:1.6201;stroke-miterlimit:10;}
+</style>
+<g id="Layer_2">
+</g>
+<g id="Layer_1">
+	<g>
+		<g>
+			<g>
+				<path class="st0" d="M96.7,26l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9V45h-5V32.9c0-1.1-0.2-1.9-0.5-2.4s-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6V45h-5V32.9
+					c0-1.1-0.1-1.9-0.4-2.4s-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4V45h-5V26H96.7z"/>
+				<path class="st0" d="M118.5,34.9c0-3.1,0.6-5.4,1.7-7s2.7-2.3,4.7-2.3c1.7,0,3.1,0.7,4,2l0.2-1.7h4.5v19c0,2.4-0.7,4.3-2,5.6
+					c-1.4,1.3-3.3,1.9-5.9,1.9c-1,0-2.1-0.2-3.3-0.6s-2-0.9-2.6-1.6l1.7-3.4c0.5,0.5,1.1,0.9,1.8,1.2c0.7,0.3,1.5,0.5,2.1,0.5
+					c1.1,0,1.9-0.3,2.4-0.8s0.7-1.4,0.7-2.6v-1.6c-0.9,1.2-2.2,1.9-3.7,1.9c-2,0-3.6-0.8-4.7-2.4s-1.7-3.8-1.7-6.7V34.9z
+					 M123.5,36.2c0,1.8,0.2,3,0.7,3.8s1.2,1.2,2.2,1.2c1,0,1.8-0.4,2.3-1.1V31c-0.5-0.8-1.3-1.2-2.2-1.2c-1,0-1.7,0.4-2.2,1.2
+					s-0.7,2.1-0.7,3.9V36.2z"/>
+				<path class="st0" d="M142.2,26l0.1,1.8c1.1-1.4,2.6-2.1,4.4-2.1c1.9,0,3.2,0.9,4,2.6c1.1-1.7,2.6-2.6,4.7-2.6
+					c3.3,0,5,2.3,5.1,6.9V45h-5V32.9c0-1.1-0.2-1.9-0.5-2.4c-0.3-0.5-0.8-0.7-1.5-0.7c-0.9,0-1.6,0.6-2.1,1.7l0,0.6V45h-5V32.9
+					c0-1.1-0.1-1.9-0.4-2.4c-0.3-0.5-0.8-0.7-1.6-0.7c-0.9,0-1.5,0.5-2,1.4V45h-5V26H142.2z"/>
+				<path class="st0" d="M170.3,21.3V26h2.5v3.7h-2.5v9.5c0,0.8,0.1,1.3,0.3,1.5c0.2,0.3,0.6,0.4,1.2,0.4c0.5,0,0.9,0,1.2-0.1l0,3.9
+					c-0.8,0.3-1.8,0.5-2.7,0.5c-3.2,0-4.8-1.8-4.9-5.5V29.7h-2.2V26h2.2v-4.7H170.3z"/>
+				<path class="st0" d="M182.7,43.5c1.4,0,2.4-0.4,3.1-1.1c0.7-0.8,1.1-1.9,1.2-3.3h1.9c-0.1,1.9-0.7,3.5-1.9,4.6s-2.6,1.7-4.3,1.7
+					c-2.3,0-4-0.7-5.1-2.2s-1.7-3.6-1.8-6.4v-2.3c0-2.9,0.6-5.1,1.7-6.6s2.9-2.2,5.1-2.2c1.9,0,3.4,0.6,4.5,1.8s1.7,2.8,1.7,5H187
+					c-0.1-1.6-0.5-2.8-1.2-3.6s-1.8-1.3-3.1-1.3c-1.7,0-2.9,0.6-3.7,1.7c-0.8,1.1-1.2,2.9-1.2,5.2v2.2c0,2.4,0.4,4.2,1.2,5.3
+					C179.8,43,181,43.5,182.7,43.5z"/>
+				<path class="st0" d="M192.6,34.5c0-2.7,0.6-4.9,1.9-6.5s2.9-2.4,5.1-2.4c2.2,0,3.9,0.8,5.1,2.4c1.2,1.6,1.9,3.7,1.9,6.5v2
+					c0,2.8-0.6,5-1.9,6.5s-2.9,2.3-5.1,2.3s-3.8-0.8-5-2.3s-1.9-3.6-1.9-6.3V34.5z M194.6,36.5c0,2.2,0.4,3.9,1.3,5.2
+					c0.9,1.3,2.1,1.9,3.7,1.9c1.6,0,2.8-0.6,3.7-1.8c0.8-1.2,1.3-2.9,1.3-5.2v-2c0-2.2-0.4-3.9-1.3-5.2c-0.9-1.3-2.1-1.9-3.7-1.9
+					c-1.5,0-2.7,0.6-3.6,1.8c-0.9,1.2-1.3,2.9-1.4,5.1V36.5z"/>
+				<path class="st0" d="M213.2,26l0.1,3c0.6-1,1.3-1.9,2.2-2.5s1.9-0.9,3-0.9c3.3,0,5,2.2,5.1,6.6V45h-1.9V32.5
+					c0-1.7-0.3-3-0.9-3.8c-0.6-0.8-1.5-1.2-2.8-1.2c-1,0-1.9,0.4-2.8,1.2s-1.4,1.8-1.9,3.2V45h-2V26H213.2z"/>
+				<path class="st0" d="M230.3,45V27.7h-2.6V26h2.6v-2.5c0-1.9,0.5-3.3,1.3-4.3s2-1.5,3.5-1.5c0.7,0,1.3,0.1,1.9,0.3l-0.1,1.8
+					c-0.5-0.1-1-0.2-1.6-0.2c-0.9,0-1.7,0.4-2.2,1.1s-0.8,1.7-0.8,3V26h3.7v1.8h-3.7V45H230.3z"/>
+				<path class="st0" d="M240.1,20.5c0-0.4,0.1-0.7,0.3-1s0.5-0.4,0.9-0.4s0.7,0.1,1,0.4s0.3,0.6,0.3,1s-0.1,0.7-0.3,1
+					s-0.5,0.4-1,0.4s-0.7-0.1-0.9-0.4S240.1,20.9,240.1,20.5z M242.3,45h-2V26h2V45z"/>
+				<path class="st0" d="M247.4,34.6c0-3,0.5-5.2,1.5-6.7s2.6-2.2,4.6-2.2c2.2,0,3.8,1,4.9,3l0.1-2.7h1.8v19.6c0,2.3-0.6,4-1.6,5.2
+					s-2.7,1.8-4.7,1.8c-1,0-2.1-0.3-3.2-0.8s-1.9-1.1-2.4-1.9l0.9-1.4c1.3,1.5,2.8,2.2,4.5,2.2c1.6,0,2.7-0.4,3.5-1.3
+					c0.7-0.8,1.1-2.1,1.1-3.8v-3c-1.1,1.8-2.7,2.7-4.9,2.7c-2,0-3.5-0.7-4.5-2.2s-1.6-3.6-1.6-6.5V34.6z M249.3,36.4
+					c0,2.4,0.4,4.2,1.1,5.4s1.9,1.7,3.5,1.7c2.1,0,3.6-1,4.5-3v-9.7c-0.9-2.2-2.4-3.3-4.4-3.3c-1.6,0-2.8,0.6-3.5,1.7
+					s-1.1,2.9-1.1,5.3V36.4z"/>
+			</g>
+		</g>
+		<g>
+			<g>
+				<g>
+					<line class="st18" x1="19.5" y1="16" x2="34.7" y2="28.5"/>
+					<g>
+						<polygon class="st0" points="18.4,18.5 16.6,13.7 21.7,14.5 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st0" cx="10.8" cy="8.1" r="8.1"/>
+			<g>
+				<g>
+					<line class="st18" x1="34.7" y1="28" x2="49.4" y2="53.3"/>
+					<g>
+						<polygon class="st0" points="46.8,54 51.2,56.5 51.2,51.4 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st18" x1="46.2" y1="31.1" x2="63.9" y2="34.9"/>
+					<g>
+						<polygon class="st0" points="46.4,33.8 42.6,30.4 47.5,28.8 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st18" x1="34.7" y1="28.5" x2="47.9" y2="20.1"/>
+					<g>
+						<polygon class="st0" points="48.7,22.7 51.1,18.1 45.9,18.3 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st18" x1="11.2" y1="33.1" x2="23.2" y2="31"/>
+					<g>
+						<polygon class="st0" points="22.9,33.7 26.8,30.4 22,28.6 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st18" x1="61.5" y1="53" x2="71.9" y2="36.1"/>
+					<g>
+						<polygon class="st0" points="64.1,53.7 59.5,56.2 59.7,51 						"/>
+					</g>
+				</g>
+			</g>
+			<g>
+				<g>
+					<line class="st18" x1="64.7" y1="24.4" x2="71.9" y2="36.6"/>
+					<g>
+						<polygon class="st0" points="62.9,26.4 62.9,21.2 67.3,23.7 						"/>
+					</g>
+				</g>
+			</g>
+			<circle class="st0" cx="34.7" cy="28.5" r="8.1"/>
+			<circle class="st0" cx="8.1" cy="33.9" r="8.1"/>
+			<circle class="st0" cx="58.3" cy="14.5" r="8.1"/>
+			<circle class="st0" cx="55.7" cy="63.3" r="8.1"/>
+			<circle class="st0" cx="71.9" cy="36.1" r="8.1"/>
+		</g>
+	</g>
+</g>
+</svg>

cli/cli.go

@@ -0,0 +1,165 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+// Package cli handles all of the core command line parsing. It's the first
+// entry point after the real main function, and it imports and runs our core
+// "lib".
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	cliUtil "github.com/purpleidea/mgmt/cli/util"
+	"github.com/purpleidea/mgmt/util/errwrap"
+
+	"github.com/alexflint/go-arg"
+)
+
+func init() {
+	if _, err := arg.NewParser(arg.Config{}, &Args{}); err != nil { // sanity check
+		panic(errwrap.Wrapf(err, "invalid args cli struct"))
+	}
+}
+
+// CLI is the entry point for using mgmt normally from the CLI.
+func CLI(ctx context.Context, data *cliUtil.Data) error {
+	// test for sanity
+	if data == nil {
+		return fmt.Errorf("this CLI was not run correctly")
+	}
+	if data.Program == "" || data.Version == "" {
+		return fmt.Errorf("program was not compiled correctly")
+	}
+	if data.Copying == "" {
+		return fmt.Errorf("program copyrights were removed, can't run")
+	}
+
+	args := Args{}
+	args.version = data.Version // copy this in
+	args.description = data.Tagline
+
+	config := arg.Config{
+		Program: data.Program,
+	}
+	parser, err := arg.NewParser(config, &args)
+	if err != nil {
+		// programming error
+		return errwrap.Wrapf(err, "cli config error")
+	}
+	err = parser.Parse(data.Args[1:]) // XXX: args[0] needs to be dropped
+	if err == arg.ErrHelp {
+		parser.WriteHelp(os.Stdout)
+		return nil
+	}
+	if err == arg.ErrVersion {
+		fmt.Printf("%s\n", data.Version) // byon: bring your own newline
+		return nil
+	}
+	if err != nil {
+		//parser.WriteHelp(os.Stdout) // TODO: is doing this helpful?
+		return cliUtil.CliParseError(err) // consistent errors
+	}
+
+	// display the license
+	if args.License {
+		fmt.Printf("%s", data.Copying) // file comes with a trailing nl
+		return nil
+	}
+
+	if ok, err := args.Run(ctx, data); err != nil {
+		return err
+	} else if ok { // did we activate one of the commands?
+		return nil
+	}
+
+	// print help if no subcommands are set
+	parser.WriteHelp(os.Stdout)
+
+	return nil
+}
+
+// Args is the CLI parsing structure and type of the parsed result. This
+// particular struct is the top-most one.
+type Args struct {
+	// XXX: We cannot have both subcommands and a positional argument.
+	// XXX: I think it's a bug of this library that it can't handle argv[0].
+	//Argv0 string `arg:"positional"`
+
+	License bool `arg:"--license" help:"display the license and exit"`
+
+	RunCmd *RunArgs `arg:"subcommand:run" help:"run code on this machine"`
+
+	DeployCmd *DeployArgs `arg:"subcommand:deploy" help:"deploy code into a cluster"`
+
+	// This never runs, it gets preempted in the real main() function.
+	// XXX: Can we do it nicely with the new arg parser? can it ignore all args?
+	EtcdCmd *EtcdArgs `arg:"subcommand:etcd" help:"run standalone etcd"`
+
+	// version is a private handle for our version string.
+	version string `arg:"-"` // ignored from parsing
+
+	// description is a private handle for our description string.
+	description string `arg:"-"` // ignored from parsing
+}
+
+// Version returns the version string. Implementing this signature is part of
+// the API for the cli library.
+func (obj *Args) Version() string {
+	return obj.version
+}
+
+// Description returns a description string. Implementing this signature is part
+// of the API for the cli library.
+func (obj *Args) Description() string {
+	return obj.description
+}
+
+// Run executes the correct subcommand. It errors if there's ever an error. It
+// returns true if we did activate one of the subcommands. It returns false if
+// we did not. This information is used so that the top-level parser can return
+// usage or help information if no subcommand activates.
+func (obj *Args) Run(ctx context.Context, data *cliUtil.Data) (bool, error) {
+	if cmd := obj.RunCmd; cmd != nil {
+		return cmd.Run(ctx, data)
+	}
+
+	if cmd := obj.DeployCmd; cmd != nil {
+		return cmd.Run(ctx, data)
+	}
+
+	// NOTE: we could return true, fmt.Errorf("...") if more than one did
+	return false, nil // nobody activated
+}
+
+// EtcdArgs is the CLI parsing structure and type of the parsed result. This
+// particular one is empty because the `etcd` subcommand is preempted in the
+// real main() function.
+type EtcdArgs struct{}

cli/deploy.go

@@ -0,0 +1,255 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+
+	cliUtil "github.com/purpleidea/mgmt/cli/util"
+	"github.com/purpleidea/mgmt/etcd/client"
+	"github.com/purpleidea/mgmt/etcd/deployer"
+	etcdfs "github.com/purpleidea/mgmt/etcd/fs"
+	"github.com/purpleidea/mgmt/gapi"
+	"github.com/purpleidea/mgmt/lib"
+	"github.com/purpleidea/mgmt/util"
+	"github.com/purpleidea/mgmt/util/errwrap"
+
+	git "github.com/go-git/go-git/v5"
+	"github.com/google/uuid"
+)
+
+// DeployArgs is the CLI parsing structure and type of the parsed result. This
+// particular one contains all the common flags for the `deploy` subcommand
+// which all frontends can use.
+type DeployArgs struct {
+	Seeds []string `arg:"--seeds,env:MGMT_SEEDS" help:"default etc client endpoint"`
+	Noop  bool     `arg:"--noop" help:"globally force all resources into no-op mode"`
+	Sema  int      `arg:"--sema" default:"-1" help:"globally add a semaphore to all resources with this lock count"`
+	NoGit bool     `arg:"--no-git" help:"don't look at git commit id for safe deploys"`
+	Force bool     `arg:"--force" help:"force a new deploy, even if the safety chain would break"`
+
+	DeployEmpty *cliUtil.EmptyArgs `arg:"subcommand:empty" help:"deploy empty payload"`
+	DeployLang  *cliUtil.LangArgs  `arg:"subcommand:lang" help:"deploy lang (mcl) payload"`
+	DeployYaml  *cliUtil.YamlArgs  `arg:"subcommand:yaml" help:"deploy yaml graph payload"`
+}
+
+// Run executes the correct subcommand. It errors if there's ever an error. It
+// returns true if we did activate one of the subcommands. It returns false if
+// we did not. This information is used so that the top-level parser can return
+// usage or help information if no subcommand activates. This particular Run is
+// the run for the main `deploy` subcommand. This always requires a frontend to
+// deploy to the cluster, but if you don't want a graph, you can use the `empty`
+// frontend. The engine backend is agnostic to which frontend is deployed, in
+// fact, you can deploy with multiple different frontends, one after another, on
+// the same engine.
+func (obj *DeployArgs) Run(ctx context.Context, data *cliUtil.Data) (bool, error) {
+	var name string
+	var args interface{}
+	if cmd := obj.DeployEmpty; cmd != nil {
+		name = cliUtil.LookupSubcommand(obj, cmd) // "empty"
+		args = cmd
+	}
+	if cmd := obj.DeployLang; cmd != nil {
+		name = cliUtil.LookupSubcommand(obj, cmd) // "lang"
+		args = cmd
+	}
+	if cmd := obj.DeployYaml; cmd != nil {
+		name = cliUtil.LookupSubcommand(obj, cmd) // "yaml"
+		args = cmd
+	}
+
+	// XXX: workaround https://github.com/alexflint/go-arg/issues/239
+	gapiNames := gapi.Names() // list of registered names
+	if l := len(obj.Seeds); name == "" && l > 1 {
+		elem := obj.Seeds[l-2] // second to last element
+		if util.StrInList(elem, gapiNames) {
+			return false, cliUtil.CliParseError(cliUtil.MissingEquals) // consistent errors
+		}
+	}
+
+	fn, exists := gapi.RegisteredGAPIs[name]
+	if !exists {
+		return false, nil // did not activate
+	}
+	gapiObj := fn()
+
+	program, version := data.Program, data.Version
+	Logf := func(format string, v ...interface{}) {
+		data.Flags.Logf("deploy: "+format, v...)
+	}
+
+	// TODO: consider adding a timeout based on an args.Timeout flag ?
+	ctx, cancel := signal.NotifyContext(ctx, os.Interrupt)
+	defer cancel()
+
+	cliUtil.Hello(program, version, data.Flags) // say hello!
+	defer Logf("goodbye!")
+
+	var hash, pHash string
+	if !obj.NoGit {
+		wd, err := os.Getwd()
+		if err != nil {
+			return false, errwrap.Wrapf(err, "could not get current working directory")
+		}
+		repo, err := git.PlainOpen(wd)
+		if err != nil {
+			return false, errwrap.Wrapf(err, "could not open git repo")
+		}
+
+		head, err := repo.Head()
+		if err != nil {
+			return false, errwrap.Wrapf(err, "could not read git HEAD")
+		}
+
+		hash = head.Hash().String() // current commit id
+		Logf("hash: %s", hash)
+
+		lo := &git.LogOptions{
+			From: head.Hash(),
+		}
+		commits, err := repo.Log(lo)
+		if err != nil {
+			return false, errwrap.Wrapf(err, "could not read git log")
+		}
+		if _, err := commits.Next(); err != nil { // skip over HEAD
+			return false, errwrap.Wrapf(err, "could not read HEAD in git log") // weird!
+		}
+		commit, err := commits.Next()
+		if err == nil { // errors are okay, we might be empty
+			pHash = commit.Hash.String() // previous commit id
+		}
+		Logf("previous deploy hash: %s", pHash)
+		if obj.Force {
+			pHash = "" // don't check this :(
+		}
+		if hash == "" {
+			return false, errwrap.Wrapf(err, "could not get git deploy hash")
+		}
+	}
+
+	uniqueid := uuid.New() // panic's if it can't generate one :P
+
+	etcdClient := client.NewClientFromSeedsNamespace(
+		obj.Seeds, // endpoints
+		lib.NS,
+	)
+	if err := etcdClient.Init(); err != nil {
+		return false, errwrap.Wrapf(err, "client Init failed")
+	}
+	defer func() {
+		err := errwrap.Wrapf(etcdClient.Close(), "client Close failed")
+		if err != nil {
+			// TODO: cause the final exit code to be non-zero
+			Logf("client cleanup error: %+v", err)
+		}
+	}()
+
+	simpleDeploy := &deployer.SimpleDeploy{
+		Client: etcdClient,
+		Debug:  data.Flags.Debug,
+		Logf: func(format string, v ...interface{}) {
+			Logf("deploy: "+format, v...)
+		},
+	}
+	if err := simpleDeploy.Init(); err != nil {
+		return false, errwrap.Wrapf(err, "deploy Init failed")
+	}
+	defer func() {
+		err := errwrap.Wrapf(simpleDeploy.Close(), "deploy Close failed")
+		if err != nil {
+			// TODO: cause the final exit code to be non-zero
+			Logf("deploy cleanup error: %+v", err)
+		}
+	}()
+
+	// get max id (from all the previous deploys)
+	max, err := simpleDeploy.GetMaxDeployID(ctx)
+	if err != nil {
+		return false, errwrap.Wrapf(err, "error getting max deploy id")
+	}
+	// find the latest id
+	var id = max + 1 // next id
+	Logf("previous max deploy id: %d", max)
+
+	etcdFs := &etcdfs.Fs{
+		Client: etcdClient,
+		// TODO: using a uuid is meant as a temporary measure, i hate them
+		Metadata:   lib.MetadataPrefix + fmt.Sprintf("/deploy/%d-%s", id, uniqueid),
+		DataPrefix: lib.StoragePrefix,
+
+		Debug: data.Flags.Debug,
+		Logf: func(format string, v ...interface{}) {
+			Logf("fs: "+format, v...)
+		},
+	}
+
+	info := &gapi.Info{
+		Args: args,
+		Flags: &gapi.Flags{
+			Noop: obj.Noop,
+			Sema: obj.Sema,
+			//Update: obj.Update,
+		},
+
+		Fs:    etcdFs,
+		Debug: data.Flags.Debug,
+		Logf: func(format string, v ...interface{}) {
+			// TODO: is this a sane prefix to use here?
+			data.Flags.Logf("cli: "+format, v...)
+		},
+	}
+
+	deploy, err := gapiObj.Cli(info)
+	if err != nil {
+		return false, cliUtil.CliParseError(err) // consistent errors
+	}
+	if deploy == nil { // not used
+		return false, fmt.Errorf("not enough information specified")
+	}
+
+	// redundant
+	deploy.Noop = obj.Noop
+	deploy.Sema = obj.Sema
+
+	str, err := deploy.ToB64()
+	if err != nil {
+		return false, errwrap.Wrapf(err, "encoding error")
+	}
+
+	// this nominally checks the previous git hash matches our expectation
+	if err := simpleDeploy.AddDeploy(ctx, id, hash, pHash, &str); err != nil {
+		return false, errwrap.Wrapf(err, "could not create deploy id `%d`", id)
+	}
+	Logf("success, id: %d", id)
+	return true, nil
+}

cli/run.go

@@ -0,0 +1,233 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package cli
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"sync"
+	"syscall"
+
+	cliUtil "github.com/purpleidea/mgmt/cli/util"
+	"github.com/purpleidea/mgmt/gapi"
+	"github.com/purpleidea/mgmt/lib"
+	"github.com/purpleidea/mgmt/util"
+	"github.com/purpleidea/mgmt/util/errwrap"
+
+	"github.com/spf13/afero"
+)
+
+// RunArgs is the CLI parsing structure and type of the parsed result. This
+// particular one contains all the common flags for the `run` subcommand which
+// all frontends can use.
+type RunArgs struct {
+	lib.Config // embedded config (can't be a pointer) https://github.com/alexflint/go-arg/issues/240
+
+	RunEmpty *cliUtil.EmptyArgs `arg:"subcommand:empty" help:"run empty payload"`
+	RunLang  *cliUtil.LangArgs  `arg:"subcommand:lang" help:"run lang (mcl) payload"`
+	RunYaml  *cliUtil.YamlArgs  `arg:"subcommand:yaml" help:"run yaml graph payload"`
+}
+
+// Run executes the correct subcommand. It errors if there's ever an error. It
+// returns true if we did activate one of the subcommands. It returns false if
+// we did not. This information is used so that the top-level parser can return
+// usage or help information if no subcommand activates. This particular Run is
+// the run for the main `run` subcommand. This always requires a frontend to
+// start the engine, but if you don't want a graph, you can use the `empty`
+// frontend. The engine backend is agnostic to which frontend is running, in
+// fact, you can deploy with multiple different frontends, one after another, on
+// the same engine.
+func (obj *RunArgs) Run(ctx context.Context, data *cliUtil.Data) (bool, error) {
+	var name string
+	var args interface{}
+	if cmd := obj.RunEmpty; cmd != nil {
+		name = cliUtil.LookupSubcommand(obj, cmd) // "empty"
+		args = cmd
+	}
+	if cmd := obj.RunLang; cmd != nil {
+		name = cliUtil.LookupSubcommand(obj, cmd) // "lang"
+		args = cmd
+	}
+	if cmd := obj.RunYaml; cmd != nil {
+		name = cliUtil.LookupSubcommand(obj, cmd) // "yaml"
+		args = cmd
+	}
+
+	// XXX: workaround https://github.com/alexflint/go-arg/issues/239
+	lists := [][]string{
+		obj.Seeds,
+		obj.ClientURLs,
+		obj.ServerURLs,
+		obj.AdvertiseClientURLs,
+		obj.AdvertiseServerURLs,
+	}
+	gapiNames := gapi.Names() // list of registered names
+	for _, list := range lists {
+		if l := len(list); name == "" && l > 1 {
+			elem := list[l-2] // second to last element
+			if util.StrInList(elem, gapiNames) {
+				return false, cliUtil.CliParseError(cliUtil.MissingEquals) // consistent errors
+			}
+		}
+	}
+
+	fn, exists := gapi.RegisteredGAPIs[name]
+	if !exists {
+		return false, nil // did not activate
+	}
+	gapiObj := fn()
+
+	main := &lib.Main{}
+	main.Config = &obj.Config // pass in all the parsed data
+
+	main.Program, main.Version = data.Program, data.Version
+	main.Debug, main.Logf = data.Flags.Debug, data.Flags.Logf // no prefix
+	Logf := func(format string, v ...interface{}) {
+		data.Flags.Logf("main: "+format, v...)
+	}
+
+	cliUtil.Hello(main.Program, main.Version, data.Flags) // say hello!
+	defer Logf("goodbye!")
+
+	// create a memory backed temporary filesystem for storing runtime data
+	mmFs := afero.NewMemMapFs()
+	afs := &afero.Afero{Fs: mmFs} // wrap so that we're implementing ioutil
+	standaloneFs := &util.AferoFs{Afero: afs}
+	main.DeployFs = standaloneFs
+
+	info := &gapi.Info{
+		Args: args,
+		Flags: &gapi.Flags{
+			Hostname: obj.Hostname,
+			Noop:     obj.Noop,
+			Sema:     obj.Sema,
+			//Update: obj.Update,
+		},
+
+		Fs:    standaloneFs,
+		Debug: data.Flags.Debug,
+		Logf: func(format string, v ...interface{}) {
+			data.Flags.Logf("cli: "+format, v...)
+		},
+	}
+
+	deploy, err := gapiObj.Cli(info)
+	if err != nil {
+		return false, cliUtil.CliParseError(err) // consistent errors
+	}
+
+	if cmd := obj.RunLang; cmd != nil && cmd.OnlyUnify && deploy == nil {
+		return true, nil // we end early
+	}
+	if cmd := obj.RunLang; cmd != nil && cmd.OnlyDownload && deploy == nil {
+		return true, nil // we end early
+	}
+	main.Deploy = deploy
+	if main.Deploy == nil {
+		// nobody activated, but we'll still watch the etcd deploy chan,
+		// and if there is deployed code that's ready to run, we'll run!
+		data.Flags.Logf("main: no frontend selected (no GAPI activated)")
+	}
+
+	if err := main.Validate(); err != nil {
+		return false, err
+	}
+
+	if err := main.Init(); err != nil {
+		return false, err
+	}
+
+	// install the exit signal handler
+	wg := &sync.WaitGroup{}
+	defer wg.Wait()
+	exit := make(chan struct{})
+	defer close(exit)
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		// must have buffer for max number of signals
+		signals := make(chan os.Signal, 3+1) // 3 * ^C + 1 * SIGTERM
+		signal.Notify(signals, os.Interrupt) // catch ^C
+		//signal.Notify(signals, os.Kill) // catch signals
+		signal.Notify(signals, syscall.SIGTERM)
+		var count uint8
+		for {
+			select {
+			case sig := <-signals: // any signal will do
+				if sig != os.Interrupt {
+					data.Flags.Logf("interrupted by signal")
+					main.Interrupt(fmt.Errorf("killed by %v", sig))
+					return
+				}
+
+				switch count {
+				case 0:
+					data.Flags.Logf("interrupted by ^C")
+					main.Exit(nil)
+				case 1:
+					data.Flags.Logf("interrupted by ^C (fast pause)")
+					main.FastExit(nil)
+				case 2:
+					data.Flags.Logf("interrupted by ^C (hard interrupt)")
+					main.Interrupt(nil)
+				}
+				count++
+
+			case <-exit:
+				return
+			}
+		}
+	}()
+
+	reterr := main.Run()
+	if reterr != nil {
+		// log the error message returned
+		if data.Flags.Debug {
+			data.Flags.Logf("main: %+v", reterr)
+		}
+	}
+
+	if err := main.Close(); err != nil {
+		if data.Flags.Debug {
+			data.Flags.Logf("main: Close: %+v", err)
+		}
+		if reterr == nil {
+			return false, err
+		}
+		reterr = errwrap.Append(reterr, err)
+	}
+
+	if reterr != nil {
+		return false, reterr
+	}
+	return true, nil
+}

cli/util/args.go

@@ -0,0 +1,102 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package util
+
+import (
+	"reflect"
+	"strings"
+)
+
+// LookupSubcommand returns the name of the subcommand in the obj, of a struct.
+// This is useful for determining the name of the subcommand that was activated.
+// It returns an empty string if a specific name was not found.
+func LookupSubcommand(obj interface{}, st interface{}) string {
+	val := reflect.ValueOf(obj)
+	if val.Kind() == reflect.Ptr { // max one de-referencing
+		val = val.Elem()
+	}
+
+	v := reflect.ValueOf(st) // value of the struct
+	typ := val.Type()
+	for i := 0; i < typ.NumField(); i++ {
+		f := val.Field(i) // value of the field
+		if f.Interface() != v.Interface() {
+			continue
+		}
+
+		field := typ.Field(i)
+		alias, ok := field.Tag.Lookup("arg")
+		if !ok {
+			continue
+		}
+
+		// XXX: `arg` needs a split by comma first or fancier parsing
+		prefix := "subcommand"
+		split := strings.Split(alias, ":")
+		if len(split) != 2 || split[0] != prefix {
+			continue
+		}
+
+		return split[1] // found
+	}
+	return "" // not found
+}
+
+// EmptyArgs is the empty CLI parsing structure and type of the parsed result.
+type EmptyArgs struct{}
+
+// LangArgs is the lang CLI parsing structure and type of the parsed result.
+type LangArgs struct {
+	// Input is the input mcl code or file path or any input specification.
+	Input string `arg:"positional,required"`
+
+	// TODO: removed (temporarily?)
+	//Stdin bool `arg:"--stdin" help:"use passthrough stdin"`
+
+	Download     bool `arg:"--download" help:"download any missing imports"`
+	OnlyDownload bool `arg:"--only-download" help:"stop after downloading any missing imports"`
+	Update       bool `arg:"--update" help:"update all dependencies to the latest versions"`
+
+	OnlyUnify bool `arg:"--only-unify" help:"stop after type unification"`
+	SkipUnify bool `arg:"--skip-unify" help:"skip type unification"`
+
+	Depth int `arg:"--depth" default:"-1" help:"max recursion depth limit (-1 is unlimited)"`
+
+	// The default of 0 means any error is a failure by default.
+	Retry int `arg:"--depth" help:"max number of retries (-1 is unlimited)"`
+
+	ModulePath string `arg:"--module-path,env:MGMT_MODULE_PATH" help:"choose the modules path (absolute)"`
+}
+
+// YamlArgs is the yaml CLI parsing structure and type of the parsed result.
+type YamlArgs struct {
+	// Input is the input yaml code or file path or any input specification.
+	Input string `arg:"positional,required"`
+}

cli/util/hello.go

@@ -0,0 +1,47 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package util
+
+import (
+	"fmt"
+	"time"
+)
+
+// Hello is a simple helper function to print a hello message and time.
+func Hello(program, version string, flags Flags) {
+	var start = time.Now().UnixNano()
+	if program == "" {
+		program = "<unknown>"
+	}
+	fmt.Println(fmt.Sprintf("This is: %s, version: %s", program, version))
+	fmt.Println("Copyright (C) 2013-2024+ James Shubin and the project contributors")
+	fmt.Println("Written by James Shubin <james@shubin.ca> and the project contributors")
+	flags.Logf("main: start: %v", start)
+}

cli/util/util.go

@@ -0,0 +1,98 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+// Package util has some CLI related utility code.
+package util
+
+import (
+	"log"
+	"os"
+	"strings"
+
+	"github.com/purpleidea/mgmt/util/errwrap"
+)
+
+// Error is a constant error type that implements error.
+type Error string
+
+// Error fulfills the error interface of this type.
+func (e Error) Error() string { return string(e) }
+
+const (
+	// MissingEquals means we probably hit the parsing bug.
+	// XXX: see: https://github.com/alexflint/go-arg/issues/239
+	MissingEquals = Error("missing equals sign for list element")
+)
+
+// CliParseError returns a consistent error if we have a CLI parsing issue.
+func CliParseError(err error) error {
+	return errwrap.Wrapf(err, "cli parse error")
+}
+
+// Flags are some constant flags which are used throughout the program.
+type Flags struct {
+	Debug bool // add additional log messages
+	Logf  func(format string, v ...interface{})
+}
+
+// Data is a struct of values that we usually pass to the main CLI function.
+type Data struct {
+	Program string
+	Version string
+	Copying string
+	Tagline string
+	Flags   Flags
+	Args    []string // os.Args usually
+}
+
+// SafeProgram returns the correct program string when given a buggy variant.
+func SafeProgram(program string) string {
+	// FIXME: in sub commands, the cli package appends a space and the sub
+	// command name at the end. hack around this by only using the first bit
+	// see: https://github.com/urfave/cli/issues/783 for more details...
+	split := strings.Split(program, " ")
+	program = split[0]
+	//if program == "" {
+	//	program = "<unknown>"
+	//}
+	return program
+}
+
+// LogSetup changes some of the core logger package settings.
+func LogSetup(debug bool) {
+	// TODO: Move these log package initialization steps to the top main.go?
+	logFlags := log.LstdFlags
+	if debug {
+		logFlags = logFlags + log.Lshortfile
+	}
+	logFlags = logFlags - log.Ldate // remove the date for now
+	log.SetFlags(logFlags)
+
+	log.SetOutput(os.Stderr)
+}

config.go

@@ -1,535 +0,0 @@
-// Mgmt
-// Copyright (C) 2013-2016+ James Shubin and the project contributors
-// Written by James Shubin <james@shubin.ca> and the project contributors
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Affero General Public License as published by
-// the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU Affero General Public License for more details.
-//
-// You should have received a copy of the GNU Affero General Public License
-// along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-package main
-
-import (
-	"errors"
-	"fmt"
-	"gopkg.in/yaml.v2"
-	"io/ioutil"
-	"log"
-	"reflect"
-	"strings"
-)
-
-type collectorResConfig struct {
-	Kind    string `yaml:"kind"`
-	Pattern string `yaml:"pattern"` // XXX: Not Implemented
-}
-
-type vertexConfig struct {
-	Kind string `yaml:"kind"`
-	Name string `yaml:"name"`
-}
-
-type edgeConfig struct {
-	Name string       `yaml:"name"`
-	From vertexConfig `yaml:"from"`
-	To   vertexConfig `yaml:"to"`
-}
-
-type GraphConfig struct {
-	Graph     string `yaml:"graph"`
-	Resources struct {
-		Noop []*NoopRes `yaml:"noop"`
-		Pkg  []*PkgRes  `yaml:"pkg"`
-		File []*FileRes `yaml:"file"`
-		Svc  []*SvcRes  `yaml:"svc"`
-		Exec []*ExecRes `yaml:"exec"`
-	} `yaml:"resources"`
-	Collector []collectorResConfig `yaml:"collect"`
-	Edges     []edgeConfig         `yaml:"edges"`
-	Comment   string               `yaml:"comment"`
-}
-
-func (c *GraphConfig) Parse(data []byte) error {
-	if err := yaml.Unmarshal(data, c); err != nil {
-		return err
-	}
-	if c.Graph == "" {
-		return errors.New("Graph config: invalid `graph`")
-	}
-	return nil
-}
-
-func ParseConfigFromFile(filename string) *GraphConfig {
-	data, err := ioutil.ReadFile(filename)
-	if err != nil {
-		log.Printf("Error: Config: ParseConfigFromFile: File: %v", err)
-		return nil
-	}
-
-	var config GraphConfig
-	if err := config.Parse(data); err != nil {
-		log.Printf("Error: Config: ParseConfigFromFile: Parse: %v", err)
-		return nil
-	}
-
-	return &config
-}
-
-// NewGraphFromConfig returns a new graph from existing input, such as from the
-// existing graph, and a GraphConfig struct.
-func (g *Graph) NewGraphFromConfig(config *GraphConfig, etcdO *EtcdWObject, hostname string) (*Graph, error) {
-
-	var graph *Graph // new graph to return
-	if g == nil {    // FIXME: how can we check for an empty graph?
-		graph = NewGraph("Graph") // give graph a default name
-	} else {
-		graph = g.Copy() // same vertices, since they're pointers!
-	}
-
-	var lookup = make(map[string]map[string]*Vertex)
-
-	//log.Printf("%+v", config) // debug
-
-	// TODO: if defined (somehow)...
-	graph.SetName(config.Graph) // set graph name
-
-	var keep []*Vertex // list of vertex which are the same in new graph
-
-	// use reflection to avoid duplicating code... better options welcome!
-	value := reflect.Indirect(reflect.ValueOf(config.Resources))
-	vtype := value.Type()
-	for i := 0; i < vtype.NumField(); i++ { // number of fields in struct
-		name := vtype.Field(i).Name // string of field name
-		field := value.FieldByName(name)
-		iface := field.Interface() // interface type of value
-		slice := reflect.ValueOf(iface)
-		// XXX: should we just drop these everywhere and have the kind strings be all lowercase?
-		kind := FirstToUpper(name)
-		if DEBUG {
-			log.Printf("Config: Processing: %v...", kind)
-		}
-		for j := 0; j < slice.Len(); j++ { // loop through resources of same kind
-			x := slice.Index(j).Interface()
-			obj, ok := x.(Res) // convert to Res type
-			if !ok {
-				return nil, fmt.Errorf("Error: Config: Can't convert: %v of type: %T to Res.", x, x)
-			}
-
-			if _, exists := lookup[kind]; !exists {
-				lookup[kind] = make(map[string]*Vertex)
-			}
-			// XXX: should we export based on a @@ prefix, or a metaparam
-			// like exported => true || exported => (host pattern)||(other pattern?)
-			if !strings.HasPrefix(obj.GetName(), "@@") { // exported resource
-				// XXX: we don't have a way of knowing if any of the
-				// metaparams are undefined, and as a result to set the
-				// defaults that we want! I hate the go yaml parser!!!
-				v := graph.GetVertexMatch(obj)
-				if v == nil { // no match found
-					obj.Init()
-					v = NewVertex(obj)
-					graph.AddVertex(v) // call standalone in case not part of an edge
-				}
-				lookup[kind][obj.GetName()] = v // used for constructing edges
-				keep = append(keep, v)          // append
-
-			} else {
-				// XXX: do this in a different function...
-				// add to etcd storage...
-				obj.SetName(obj.GetName()[2:]) //slice off @@
-
-				data, err := ResToB64(obj)
-				if err != nil {
-					return nil, fmt.Errorf("Config: Could not encode %v resource: %v, error: %v", kind, obj.GetName(), err)
-				}
-
-				if !etcdO.EtcdPut(hostname, obj.GetName(), kind, data) {
-					return nil, fmt.Errorf("Config: Could not export %v resource: %v", kind, obj.GetName())
-				}
-			}
-		}
-	}
-
-	// lookup from etcd graph
-	// do all the graph look ups in one single step, so that if the etcd
-	// database changes, we don't have a partial state of affairs...
-	nodes, ok := etcdO.EtcdGet()
-	if ok {
-		for _, t := range config.Collector {
-			// XXX: should we just drop these everywhere and have the kind strings be all lowercase?
-			kind := FirstToUpper(t.Kind)
-
-			// use t.Kind and optionally t.Pattern to collect from etcd storage
-			log.Printf("Collect: %v; Pattern: %v", kind, t.Pattern)
-			for _, str := range etcdO.EtcdGetProcess(nodes, kind) {
-				obj, err := B64ToRes(str)
-				if err != nil {
-					log.Printf("B64ToRes failed to decode: %v", err)
-					log.Printf("Collect: %v: not collected!", kind)
-					continue
-				}
-
-				if t.Pattern != "" { // XXX: simplistic for now
-					obj.CollectPattern(t.Pattern) // obj.Dirname = t.Pattern
-				}
-
-				log.Printf("Collect: %v[%v]: collected!", kind, obj.GetName())
-
-				// XXX: similar to other resource add code:
-				if _, exists := lookup[kind]; !exists {
-					lookup[kind] = make(map[string]*Vertex)
-				}
-				v := graph.GetVertexMatch(obj)
-				if v == nil { // no match found
-					obj.Init() // initialize go channels or things won't work!!!
-					v = NewVertex(obj)
-					graph.AddVertex(v) // call standalone in case not part of an edge
-				}
-				lookup[kind][obj.GetName()] = v // used for constructing edges
-				keep = append(keep, v)          // append
-			}
-		}
-	}
-
-	// get rid of any vertices we shouldn't "keep" (that aren't in new graph)
-	for _, v := range graph.GetVertices() {
-		if !VertexContains(v, keep) {
-			// wait for exit before starting new graph!
-			v.SendEvent(eventExit, true, false)
-			graph.DeleteVertex(v)
-		}
-	}
-
-	for _, e := range config.Edges {
-		if _, ok := lookup[FirstToUpper(e.From.Kind)]; !ok {
-			return nil, fmt.Errorf("Can't find 'from' resource!")
-		}
-		if _, ok := lookup[FirstToUpper(e.To.Kind)]; !ok {
-			return nil, fmt.Errorf("Can't find 'to' resource!")
-		}
-		if _, ok := lookup[FirstToUpper(e.From.Kind)][e.From.Name]; !ok {
-			return nil, fmt.Errorf("Can't find 'from' name!")
-		}
-		if _, ok := lookup[FirstToUpper(e.To.Kind)][e.To.Name]; !ok {
-			return nil, fmt.Errorf("Can't find 'to' name!")
-		}
-		graph.AddEdge(lookup[FirstToUpper(e.From.Kind)][e.From.Name], lookup[FirstToUpper(e.To.Kind)][e.To.Name], NewEdge(e.Name))
-	}
-
-	return graph, nil
-}
-
-// add edges to the vertex in a graph based on if it matches a uuid list
-func (g *Graph) addEdgesByMatchingUUIDS(v *Vertex, uuids []ResUUID) []bool {
-	// search for edges and see what matches!
-	var result []bool
-
-	// loop through each uuid, and see if it matches any vertex
-	for _, uuid := range uuids {
-		var found = false
-		// uuid is a ResUUID object
-		for _, vv := range g.GetVertices() { // search
-			if v == vv { // skip self
-				continue
-			}
-			if DEBUG {
-				log.Printf("Compile: AutoEdge: Match: %v[%v] with UUID: %v[%v]", vv.Kind(), vv.GetName(), uuid.Kind(), uuid.GetName())
-			}
-			// we must match to an effective UUID for the resource,
-			// that is to say, the name value of a res is a helpful
-			// handle, but it is not necessarily a unique identity!
-			// remember, resources can return multiple UUID's each!
-			if UUIDExistsInUUIDs(uuid, vv.GetUUIDs()) {
-				// add edge from: vv -> v
-				if uuid.Reversed() {
-					txt := fmt.Sprintf("AutoEdge: %v[%v] -> %v[%v]", vv.Kind(), vv.GetName(), v.Kind(), v.GetName())
-					log.Printf("Compile: Adding %v", txt)
-					g.AddEdge(vv, v, NewEdge(txt))
-				} else { // edges go the "normal" way, eg: pkg resource
-					txt := fmt.Sprintf("AutoEdge: %v[%v] -> %v[%v]", v.Kind(), v.GetName(), vv.Kind(), vv.GetName())
-					log.Printf("Compile: Adding %v", txt)
-					g.AddEdge(v, vv, NewEdge(txt))
-				}
-				found = true
-				break
-			}
-		}
-		result = append(result, found)
-	}
-	return result
-}
-
-// add auto edges to graph
-func (g *Graph) AutoEdges() {
-	log.Println("Compile: Adding AutoEdges...")
-	for _, v := range g.GetVertices() { // for each vertexes autoedges
-		if !v.GetMeta().AutoEdge { // is the metaparam true?
-			continue
-		}
-		autoEdgeObj := v.AutoEdges()
-		if autoEdgeObj == nil {
-			log.Printf("%v[%v]: Config: No auto edges were found!", v.Kind(), v.GetName())
-			continue // next vertex
-		}
-
-		for { // while the autoEdgeObj has more uuids to add...
-			uuids := autoEdgeObj.Next() // get some!
-			if uuids == nil {
-				log.Printf("%v[%v]: Config: The auto edge list is empty!", v.Kind(), v.GetName())
-				break // inner loop
-			}
-			if DEBUG {
-				log.Println("Compile: AutoEdge: UUIDS:")
-				for i, u := range uuids {
-					log.Printf("Compile: AutoEdge: UUID%d: %v", i, u)
-				}
-			}
-
-			// match and add edges
-			result := g.addEdgesByMatchingUUIDS(v, uuids)
-
-			// report back, and find out if we should continue
-			if !autoEdgeObj.Test(result) {
-				break
-			}
-		}
-	}
-}
-
-// AutoGrouper is the required interface to implement for an autogroup algorithm
-type AutoGrouper interface {
-	// listed in the order these are typically called in...
-	name() string                                  // friendly identifier
-	init(*Graph) error                             // only call once
-	vertexNext() (*Vertex, *Vertex, error)         // mostly algorithmic
-	vertexCmp(*Vertex, *Vertex) error              // can we merge these ?
-	vertexMerge(*Vertex, *Vertex) (*Vertex, error) // vertex merge fn to use
-	edgeMerge(*Edge, *Edge) *Edge                  // edge merge fn to use
-	vertexTest(bool) (bool, error)                 // call until false
-}
-
-// baseGrouper is the base type for implementing the AutoGrouper interface
-type baseGrouper struct {
-	graph    *Graph    // store a pointer to the graph
-	vertices []*Vertex // cached list of vertices
-	i        int
-	j        int
-	done     bool
-}
-
-// name provides a friendly name for the logs to see
-func (ag *baseGrouper) name() string {
-	return "baseGrouper"
-}
-
-// init is called only once and before using other AutoGrouper interface methods
-// the name method is the only exception: call it any time without side effects!
-func (ag *baseGrouper) init(g *Graph) error {
-	if ag.graph != nil {
-		return fmt.Errorf("The init method has already been called!")
-	}
-	ag.graph = g                               // pointer
-	ag.vertices = ag.graph.GetVerticesSorted() // cache in deterministic order!
-	ag.i = 0
-	ag.j = 0
-	if len(ag.vertices) == 0 { // empty graph
-		ag.done = true
-		return nil
-	}
-	return nil
-}
-
-// vertexNext is a simple iterator that loops through vertex (pair) combinations
-// an intelligent algorithm would selectively offer only valid pairs of vertices
-// these should satisfy logical grouping requirements for the autogroup designs!
-// the desired algorithms can override, but keep this method as a base iterator!
-func (ag *baseGrouper) vertexNext() (v1, v2 *Vertex, err error) {
-	// this does a for v... { for w... { return v, w }} but stepwise!
-	l := len(ag.vertices)
-	if ag.i < l {
-		v1 = ag.vertices[ag.i]
-	}
-	if ag.j < l {
-		v2 = ag.vertices[ag.j]
-	}
-
-	// in case the vertex was deleted
-	if !ag.graph.HasVertex(v1) {
-		v1 = nil
-	}
-	if !ag.graph.HasVertex(v2) {
-		v2 = nil
-	}
-
-	// two nested loops...
-	if ag.j < l {
-		ag.j++
-	}
-	if ag.j == l {
-		ag.j = 0
-		if ag.i < l {
-			ag.i++
-		}
-		if ag.i == l {
-			ag.done = true
-		}
-	}
-
-	return
-}
-
-func (ag *baseGrouper) vertexCmp(v1, v2 *Vertex) error {
-	if v1 == nil || v2 == nil {
-		return fmt.Errorf("Vertex is nil!")
-	}
-	if v1 == v2 { // skip yourself
-		return fmt.Errorf("Vertices are the same!")
-	}
-	if v1.Kind() != v2.Kind() { // we must group similar kinds
-		// TODO: maybe future resources won't need this limitation?
-		return fmt.Errorf("The two resources aren't the same kind!")
-	}
-	// someone doesn't want to group!
-	if !v1.GetMeta().AutoGroup || !v2.GetMeta().AutoGroup {
-		return fmt.Errorf("One of the autogroup flags is false!")
-	}
-	if v1.Res.IsGrouped() { // already grouped!
-		return fmt.Errorf("Already grouped!")
-	}
-	if len(v2.Res.GetGroup()) > 0 { // already has children grouped!
-		return fmt.Errorf("Already has groups!")
-	}
-	if !v1.Res.GroupCmp(v2.Res) { // resource groupcmp failed!
-		return fmt.Errorf("The GroupCmp failed!")
-	}
-	return nil // success
-}
-
-func (ag *baseGrouper) vertexMerge(v1, v2 *Vertex) (v *Vertex, err error) {
-	// NOTE: it's important to use w.Res instead of w, b/c
-	// the w by itself is the *Vertex obj, not the *Res obj
-	// which is contained within it! They both satisfy the
-	// Res interface, which is why both will compile! :(
-	err = v1.Res.GroupRes(v2.Res) // GroupRes skips stupid groupings
-	return                        // success or fail, and no need to merge the actual vertices!
-}
-
-func (ag *baseGrouper) edgeMerge(e1, e2 *Edge) *Edge {
-	return e1 // noop
-}
-
-// vertexTest processes the results of the grouping for the algorithm to know
-// return an error if something went horribly wrong, and bool false to stop
-func (ag *baseGrouper) vertexTest(b bool) (bool, error) {
-	// NOTE: this particular baseGrouper version doesn't track what happens
-	// because since we iterate over every pair, we don't care which merge!
-	if ag.done {
-		return false, nil
-	}
-	return true, nil
-}
-
-// TODO: this algorithm may not be correct in all cases. replace if needed!
-type nonReachabilityGrouper struct {
-	baseGrouper // "inherit" what we want, and reimplement the rest
-}
-
-func (ag *nonReachabilityGrouper) name() string {
-	return "nonReachabilityGrouper"
-}
-
-// this algorithm relies on the observation that if there's a path from a to b,
-// then they *can't* be merged (b/c of the existing dependency) so therefore we
-// merge anything that *doesn't* satisfy this condition or that of the reverse!
-func (ag *nonReachabilityGrouper) vertexNext() (v1, v2 *Vertex, err error) {
-	for {
-		v1, v2, err = ag.baseGrouper.vertexNext() // get all iterable pairs
-		if err != nil {
-			log.Fatalf("Error running autoGroup(vertexNext): %v", err)
-		}
-
-		if v1 != v2 { // ignore self cmp early (perf optimization)
-			// if NOT reachable, they're viable...
-			out1 := ag.graph.Reachability(v1, v2)
-			out2 := ag.graph.Reachability(v2, v1)
-			if len(out1) == 0 && len(out2) == 0 {
-				return // return v1 and v2, they're viable
-			}
-		}
-
-		// if we got here, it means we're skipping over this candidate!
-		if ok, err := ag.baseGrouper.vertexTest(false); err != nil {
-			log.Fatalf("Error running autoGroup(vertexTest): %v", err)
-		} else if !ok {
-			return nil, nil, nil // done!
-		}
-
-		// the vertexTest passed, so loop and try with a new pair...
-	}
-}
-
-// autoGroup is the mechanical auto group "runner" that runs the interface spec
-func (g *Graph) autoGroup(ag AutoGrouper) chan string {
-	strch := make(chan string) // output log messages here
-	go func(strch chan string) {
-		strch <- fmt.Sprintf("Compile: Grouping: Algorithm: %v...", ag.name())
-		if err := ag.init(g); err != nil {
-			log.Fatalf("Error running autoGroup(init): %v", err)
-		}
-
-		for {
-			var v, w *Vertex
-			v, w, err := ag.vertexNext() // get pair to compare
-			if err != nil {
-				log.Fatalf("Error running autoGroup(vertexNext): %v", err)
-			}
-			merged := false
-			// save names since they change during the runs
-			vStr := fmt.Sprintf("%s", v) // valid even if it is nil
-			wStr := fmt.Sprintf("%s", w)
-
-			if err := ag.vertexCmp(v, w); err != nil { // cmp ?
-				if DEBUG {
-					strch <- fmt.Sprintf("Compile: Grouping: !GroupCmp for: %s into %s", wStr, vStr)
-				}
-
-				// remove grouped vertex and merge edges (res is safe)
-			} else if err := g.VertexMerge(v, w, ag.vertexMerge, ag.edgeMerge); err != nil { // merge...
-				strch <- fmt.Sprintf("Compile: Grouping: !VertexMerge for: %s into %s", wStr, vStr)
-
-			} else { // success!
-				strch <- fmt.Sprintf("Compile: Grouping: Success for: %s into %s", wStr, vStr)
-				merged = true // woo
-			}
-
-			// did these get used?
-			if ok, err := ag.vertexTest(merged); err != nil {
-				log.Fatalf("Error running autoGroup(vertexTest): %v", err)
-			} else if !ok {
-				break // done!
-			}
-		}
-
-		close(strch)
-		return
-	}(strch) // call function
-	return strch
-}
-
-// AutoGroup runs the auto grouping on the graph and prints out log messages
-func (g *Graph) AutoGroup() {
-	// receive log messages from channel...
-	// this allows test cases to avoid printing them when they're unwanted!
-	// TODO: this algorithm may not be correct in all cases. replace if needed!
-	for str := range g.autoGroup(&nonReachabilityGrouper{}) {
-		log.Println(str)
-	}
-}

configwatch.go

@@ -1,155 +0,0 @@
-// Mgmt
-// Copyright (C) 2013-2016+ James Shubin and the project contributors
-// Written by James Shubin <james@shubin.ca> and the project contributors
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Affero General Public License as published by
-// the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU Affero General Public License for more details.
-//
-// You should have received a copy of the GNU Affero General Public License
-// along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-package main
-
-import (
-	"gopkg.in/fsnotify.v1"
-	//"github.com/go-fsnotify/fsnotify" // git master of "gopkg.in/fsnotify.v1"
-	"log"
-	"math"
-	"path"
-	"strings"
-	"syscall"
-)
-
-// XXX: it would be great if we could reuse code between this and the file resource
-// XXX: patch this to submit it as part of go-fsnotify if they're interested...
-func ConfigWatch(file string) chan bool {
-	ch := make(chan bool)
-	go func() {
-		var safename = path.Clean(file) // no trailing slash
-
-		watcher, err := fsnotify.NewWatcher()
-		if err != nil {
-			log.Fatal(err)
-		}
-		defer watcher.Close()
-
-		patharray := PathSplit(safename) // tokenize the path
-		var index = len(patharray)       // starting index
-		var current string               // current "watcher" location
-		var deltaDepth int               // depth delta between watcher and event
-		var send = false                 // send event?
-
-		for {
-			current = strings.Join(patharray[0:index], "/")
-			if current == "" { // the empty string top is the root dir ("/")
-				current = "/"
-			}
-			log.Printf("Watching: %v", current) // attempting to watch...
-
-			// initialize in the loop so that we can reset on rm-ed handles
-			err = watcher.Add(current)
-			if err != nil {
-				if err == syscall.ENOENT {
-					index-- // usually not found, move up one dir
-				} else if err == syscall.ENOSPC {
-					// XXX: occasionally: no space left on device,
-					// XXX: probably due to lack of inotify watches
-					log.Printf("Out of inotify watches for config(%v)", file)
-					log.Fatal(err)
-				} else {
-					log.Printf("Unknown config(%v) error:", file)
-					log.Fatal(err)
-				}
-				index = int(math.Max(1, float64(index)))
-				continue
-			}
-
-			select {
-			case event := <-watcher.Events:
-				// the deeper you go, the bigger the deltaDepth is...
-				// this is the difference between what we're watching,
-				// and the event... doesn't mean we can't watch deeper
-				if current == event.Name {
-					deltaDepth = 0 // i was watching what i was looking for
-
-				} else if HasPathPrefix(event.Name, current) {
-					deltaDepth = len(PathSplit(current)) - len(PathSplit(event.Name)) // -1 or less
-
-				} else if HasPathPrefix(current, event.Name) {
-					deltaDepth = len(PathSplit(event.Name)) - len(PathSplit(current)) // +1 or more
-
-				} else {
-					// TODO different watchers get each others events!
-					// https://github.com/go-fsnotify/fsnotify/issues/95
-					// this happened with two values such as:
-					// event.Name: /tmp/mgmt/f3 and current: /tmp/mgmt/f2
-					continue
-				}
-				//log.Printf("The delta depth is: %v", deltaDepth)
-
-				// if we have what we wanted, awesome, send an event...
-				if event.Name == safename {
-					//log.Println("Event!")
-					send = true
-
-					// file removed, move the watch upwards
-					if deltaDepth >= 0 && (event.Op&fsnotify.Remove == fsnotify.Remove) {
-						//log.Println("Removal!")
-						watcher.Remove(current)
-						index--
-					}
-
-					// we must be a parent watcher, so descend in
-					if deltaDepth < 0 {
-						watcher.Remove(current)
-						index++
-					}
-
-					// if safename starts with event.Name, we're above, and no event should be sent
-				} else if HasPathPrefix(safename, event.Name) {
-					//log.Println("Above!")
-
-					if deltaDepth >= 0 && (event.Op&fsnotify.Remove == fsnotify.Remove) {
-						log.Println("Removal!")
-						watcher.Remove(current)
-						index--
-					}
-
-					if deltaDepth < 0 {
-						log.Println("Parent!")
-						if PathPrefixDelta(safename, event.Name) == 1 { // we're the parent dir
-							//send = true
-						}
-						watcher.Remove(current)
-						index++
-					}
-
-					// if event.Name startswith safename, send event, we're already deeper
-				} else if HasPathPrefix(event.Name, safename) {
-					//log.Println("Event2!")
-					//send = true
-				}
-
-			case err := <-watcher.Errors:
-				log.Printf("error: %v", err)
-				log.Fatal(err)
-
-			}
-
-			// do our event sending all together to avoid duplicate msgs
-			if send {
-				send = false
-				ch <- true
-			}
-		}
-		//close(ch)
-	}()
-	return ch
-}

converger/converger.go

@@ -0,0 +1,495 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+// Package converger is a facility for reporting the converged state.
+package converger
+
+import (
+	"fmt"
+	"sort"
+	"sync"
+	"time"
+
+	"github.com/purpleidea/mgmt/util"
+	"github.com/purpleidea/mgmt/util/errwrap"
+)
+
+// New builds a new converger coordinator.
+func New(timeout int) *Coordinator {
+	return &Coordinator{
+		timeout: timeout,
+
+		mutex: &sync.RWMutex{},
+
+		//lastid: 0,
+		status: make(map[*UID]struct{}),
+
+		//converged: false, // initial state
+
+		pokeChan: make(chan struct{}, 1), // must be buffered
+
+		readyChan: make(chan struct{}), // ready signal
+
+		//paused: false, // starts off as started
+		pauseSignal: make(chan struct{}),
+		//resumeSignal: make(chan struct{}), // happens on pause
+		//pausedAck: util.NewEasyAck(), // happens on pause
+
+		stateFns: make(map[string]func(bool) error),
+		smutex:   &sync.RWMutex{},
+
+		closeChan: make(chan struct{}),
+		wg:        &sync.WaitGroup{},
+	}
+}
+
+// Coordinator is the central converger engine.
+type Coordinator struct {
+	// timeout must be zero (instant) or greater seconds to run. If it's -1
+	// then this is disabled, and we never run stateFns.
+	timeout int
+
+	// mutex is used for controlling access to status and lastid.
+	mutex *sync.RWMutex
+
+	// lastid contains the last uid we used for registration.
+	//lastid    uint64
+	// status contains a reference to each active UID.
+	status map[*UID]struct{}
+
+	// converged stores the last convergence state. When this changes, we
+	// run the stateFns.
+	converged bool
+
+	// pokeChan receives a message every time we might need to re-calculate.
+	pokeChan chan struct{}
+
+	// readyChan closes to notify any interested parties that the main loop
+	// is running.
+	readyChan chan struct{}
+
+	// paused represents if this coordinator is paused or not.
+	paused bool
+	// pauseSignal closes to request a pause of this coordinator.
+	pauseSignal chan struct{}
+	// resumeSignal closes to request a resume of this coordinator.
+	resumeSignal chan struct{}
+	// pausedAck is used to send an ack message saying that we've paused.
+	pausedAck *util.EasyAck
+
+	// stateFns run on converged state changes.
+	stateFns map[string]func(bool) error
+	// smutex is used for controlling access to the stateFns map.
+	smutex *sync.RWMutex
+
+	// closeChan closes when we've been requested to shutdown.
+	closeChan chan struct{}
+	// wg waits for everything to finish.
+	wg *sync.WaitGroup
+}
+
+// Register creates a new UID which can be used to report converged state. You
+// must Unregister each UID before Shutdown will be able to finish running.
+func (obj *Coordinator) Register() *UID {
+	obj.wg.Add(1) // additional tracking for each UID
+	obj.mutex.Lock()
+	defer obj.mutex.Unlock()
+	//obj.lastid++
+	uid := &UID{
+		timeout: obj.timeout, // copy the timeout here
+		//id: obj.lastid,
+		//name: fmt.Sprintf("%d", obj.lastid), // some default
+
+		poke: obj.poke,
+
+		// timer
+		mutex:   &sync.Mutex{},
+		timer:   nil,
+		running: false,
+		wg:      &sync.WaitGroup{},
+	}
+	uid.unregister = func() { obj.Unregister(uid) } // add unregister func
+	obj.status[uid] = struct{}{}                    // TODO: add converged state here?
+	return uid
+}
+
+// Unregister removes the UID from the converger coordinator. If you supply an
+// invalid or unregistered uid to this function, it will panic. An unregistered
+// UID is no longer part of the convergence checking.
+func (obj *Coordinator) Unregister(uid *UID) {
+	defer obj.wg.Done() // additional tracking for each UID
+	obj.mutex.Lock()
+	defer obj.mutex.Unlock()
+
+	if _, exists := obj.status[uid]; !exists {
+		panic("uid is not registered")
+	}
+	uid.StopTimer() // ignore any errors
+	delete(obj.status, uid)
+}
+
+// Run starts the main loop for the converger coordinator. It is commonly run
+// from a go routine. It blocks until the Shutdown method is run to close it.
+// NOTE: when we have very short timeouts, if we start before all the resources
+// have joined the map, then it might appear as if we converged before we did!
+func (obj *Coordinator) Run(startPaused bool) {
+	obj.wg.Add(1)
+	wg := &sync.WaitGroup{} // needed for the startPaused
+	defer wg.Wait()         // don't leave any leftover go routines running
+	if startPaused {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			obj.Pause() // ignore any errors
+			close(obj.readyChan)
+		}()
+	} else {
+		close(obj.readyChan) // we must wait till the wg.Add(1) has happened...
+	}
+	defer obj.wg.Done()
+	for {
+		// pause if one was requested...
+		select {
+		case <-obj.pauseSignal: // channel closes
+			obj.pausedAck.Ack() // send ack
+			// we are paused now, and waiting for resume or exit...
+			select {
+			case <-obj.resumeSignal: // channel closes
+				// resumed!
+
+			case <-obj.closeChan: // we can always escape
+				return
+			}
+
+		case _, ok := <-obj.pokeChan: // we got an event (re-calculate)
+			if !ok {
+				return
+			}
+
+			if err := obj.test(); err != nil {
+				// FIXME: what to do on error ?
+			}
+
+		case <-obj.closeChan: // we can always escape
+			return
+		}
+	}
+}
+
+// Ready blocks until the Run loop has started up. This is useful so that we
+// don't run Shutdown before we've even started up properly.
+func (obj *Coordinator) Ready() {
+	select {
+	case <-obj.readyChan:
+	}
+}
+
+// Shutdown sends a signal to the Run loop that it should exit. This blocks
+// until it does.
+func (obj *Coordinator) Shutdown() {
+	close(obj.closeChan)
+	obj.wg.Wait()
+	close(obj.pokeChan) // free memory?
+}
+
+// Pause pauses the coordinator. It should not be called on an already paused
+// coordinator. It will block until the coordinator pauses with an
+// acknowledgment, or until an exit is requested. If the latter happens it will
+// error. It is NOT thread-safe with the Resume() method so only call either one
+// at a time.
+func (obj *Coordinator) Pause() error {
+	if obj.paused {
+		return fmt.Errorf("already paused")
+	}
+
+	obj.pausedAck = util.NewEasyAck()
+	obj.resumeSignal = make(chan struct{}) // build the resume signal
+	close(obj.pauseSignal)
+
+	// wait for ack (or exit signal)
+	select {
+	case <-obj.pausedAck.Wait(): // we got it!
+		// we're paused
+	case <-obj.closeChan:
+		return fmt.Errorf("closing")
+	}
+	obj.paused = true
+
+	return nil
+}
+
+// Resume unpauses the coordinator. It can be safely called on a brand-new
+// coordinator that has just started running without incident. It is NOT
+// thread-safe with the Pause() method, so only call either one at a time.
+func (obj *Coordinator) Resume() {
+	// TODO: do we need a mutex around Resume?
+	if !obj.paused { // no need to unpause brand-new resources
+		return
+	}
+
+	obj.pauseSignal = make(chan struct{}) // rebuild for next pause
+	close(obj.resumeSignal)
+	obj.poke() // unblock and notice the resume if necessary
+
+	obj.paused = false
+
+	// no need to wait for it to resume
+	//return // implied
+}
+
+// poke sends a message to the coordinator telling it that it should re-evaluate
+// whether we're converged or not. This does not block. Do not run this in a
+// goroutine. It must not be called after Shutdown has been called.
+func (obj *Coordinator) poke() {
+	// redundant
+	//if len(obj.pokeChan) > 0 {
+	//	return
+	//}
+
+	select {
+	case obj.pokeChan <- struct{}{}:
+	default: // if chan is now full because more than one poke happened...
+	}
+}
+
+// IsConverged returns true if *every* registered uid has converged. If there
+// are no registered UID's, then this will return true.
+func (obj *Coordinator) IsConverged() bool {
+	for _, v := range obj.Status() {
+		if !v { // everyone must be converged for this to be true
+			return false
+		}
+	}
+	return true
+}
+
+// test evaluates whether we're converged or not and runs the state change. It
+// is NOT thread-safe.
+func (obj *Coordinator) test() error {
+	// TODO: add these checks elsewhere to prevent anything from running?
+	if obj.timeout < 0 {
+		return nil // nothing to do (only run if timeout is valid)
+	}
+
+	converged := obj.IsConverged()
+	defer func() {
+		obj.converged = converged // set this only at the end...
+	}()
+
+	if !converged {
+		if !obj.converged { // were we previously also not converged?
+			return nil // nothing to do
+		}
+
+		// we're doing a state change
+		// call the arbitrary functions (takes a read lock!)
+		return obj.runStateFns(false)
+	}
+
+	// we have converged!
+	if obj.converged { // were we previously also converged?
+		return nil // nothing to do
+	}
+
+	// call the arbitrary functions (takes a read lock!)
+	return obj.runStateFns(true)
+}
+
+// runStateFns runs the list of stored state functions.
+func (obj *Coordinator) runStateFns(converged bool) error {
+	obj.smutex.RLock()
+	defer obj.smutex.RUnlock()
+	var keys []string
+	for k := range obj.stateFns {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	var err error
+	for _, name := range keys { // run in deterministic order
+		fn := obj.stateFns[name]
+		// call an arbitrary function
+		e := fn(converged)
+		err = errwrap.Append(err, e) // list of errors
+	}
+	return err
+}
+
+// AddStateFn adds a state function to be run on change of converged state.
+func (obj *Coordinator) AddStateFn(name string, stateFn func(bool) error) error {
+	obj.smutex.Lock()
+	defer obj.smutex.Unlock()
+	if _, exists := obj.stateFns[name]; exists {
+		return fmt.Errorf("a stateFn with that name already exists")
+	}
+	obj.stateFns[name] = stateFn
+	return nil
+}
+
+// RemoveStateFn removes a state function from running on change of converged
+// state.
+func (obj *Coordinator) RemoveStateFn(name string) error {
+	obj.smutex.Lock()
+	defer obj.smutex.Unlock()
+	if _, exists := obj.stateFns[name]; !exists {
+		return fmt.Errorf("a stateFn with that name doesn't exist")
+	}
+	delete(obj.stateFns, name)
+	return nil
+}
+
+// Status returns a map of the converged status of each UID.
+func (obj *Coordinator) Status() map[*UID]bool {
+	status := make(map[*UID]bool)
+	obj.mutex.RLock() // take a read lock
+	defer obj.mutex.RUnlock()
+	for k := range obj.status {
+		status[k] = k.IsConverged()
+	}
+	return status
+}
+
+// Timeout returns the timeout in seconds that converger was created with. This
+// is useful to avoid passing in the timeout value separately when you're
+// already passing in the Coordinator struct.
+func (obj *Coordinator) Timeout() int {
+	return obj.timeout
+}
+
+// UID represents one of the probes for the converger coordinator. It is created
+// by calling the Register method of the Coordinator struct. It should be freed
+// after use with Unregister.
+type UID struct {
+	// timeout is a copy of the main timeout. It could eventually be used
+	// for per-UID timeouts too.
+	timeout int
+	// isConverged stores the convergence state of this particular UID.
+	isConverged bool
+
+	// poke stores a reference to the main poke function.
+	poke func()
+	// unregister stores a reference to the unregister function.
+	unregister func()
+
+	// timer
+	mutex   *sync.Mutex
+	timer   chan struct{}
+	running bool // is the timer running?
+	wg      *sync.WaitGroup
+}
+
+// Unregister removes this UID from the converger coordinator. An unregistered
+// UID is no longer part of the convergence checking.
+func (obj *UID) Unregister() {
+	obj.unregister()
+}
+
+// IsConverged reports whether this UID is converged or not.
+func (obj *UID) IsConverged() bool {
+	return obj.isConverged
+}
+
+// SetConverged sets the convergence state of this UID. This is used by the
+// running timer if one is started. The timer will overwrite any value set by
+// this method.
+func (obj *UID) SetConverged(isConverged bool) {
+	obj.isConverged = isConverged
+	obj.poke() // notify of change
+}
+
+// ConvergedTimer adds a timeout to a select call and blocks until then.
+// TODO: this means we could eventually have per resource converged timeouts
+func (obj *UID) ConvergedTimer() <-chan time.Time {
+	// be clever: if i'm already converged, this timeout should block which
+	// avoids unnecessary new signals being sent! this avoids fast loops if
+	// we have a low timeout, or in particular a timeout == 0
+	if obj.IsConverged() {
+		// blocks the case statement in select forever!
+		return util.TimeAfterOrBlock(-1)
+	}
+	return util.TimeAfterOrBlock(int(obj.timeout))
+}
+
+// StartTimer runs a timer that sets us as converged on timeout. It also returns
+// a handle to the StopTimer function which should be run before exit.
+func (obj *UID) StartTimer() (func() error, error) {
+	obj.mutex.Lock()
+	defer obj.mutex.Unlock()
+	if obj.running {
+		return obj.StopTimer, fmt.Errorf("timer already started")
+	}
+	obj.timer = make(chan struct{})
+	obj.running = true
+	obj.wg.Add(1)
+	go func() {
+		defer obj.wg.Done()
+		for {
+			select {
+			case _, ok := <-obj.timer: // reset signal channel
+				if !ok {
+					return
+				}
+				obj.SetConverged(false)
+
+			case <-obj.ConvergedTimer():
+				obj.SetConverged(true) // converged!
+				select {
+				case _, ok := <-obj.timer: // reset signal channel
+					if !ok {
+						return
+					}
+				}
+			}
+		}
+	}()
+	return obj.StopTimer, nil
+}
+
+// ResetTimer resets the timer to zero.
+func (obj *UID) ResetTimer() error {
+	obj.mutex.Lock()
+	defer obj.mutex.Unlock()
+	if obj.running {
+		obj.timer <- struct{}{} // send the reset message
+		return nil
+	}
+	return fmt.Errorf("timer hasn't been started")
+}
+
+// StopTimer stops the running timer.
+func (obj *UID) StopTimer() error {
+	obj.mutex.Lock()
+	defer obj.mutex.Unlock()
+	if !obj.running {
+		return fmt.Errorf("timer isn't running")
+	}
+	close(obj.timer)
+	obj.wg.Wait()
+	obj.running = false
+	return nil
+}

converger/converger_test.go

@@ -0,0 +1,43 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+//go:build !root
+
+package converger
+
+import (
+	"testing"
+)
+
+func TestBufferedChan1(t *testing.T) {
+	ch := make(chan bool, 1)
+	ch <- true
+	close(ch) // closing a channel that's not empty should not block
+	// must be able to exit without blocking anywhere
+}

debian/.gitignore

@@ -0,0 +1,7 @@
+*.debhelper.log
+*debhelper
+changelog
+debhelper-build-stamp
+files
+mgmt.substvars
+mgmt/*

debian/compat

@@ -0,0 +1 @@
+9

debian/control

@@ -0,0 +1,17 @@
+Source: mgmt
+Maintainer: Johan Bloemberg (aequitas) <mgmt@ijohan.nl>
+Build-Depends:
+               debhelper,
+               devscripts,
+               dh-golang,
+               dh-systemd,
+               golang-go,
+
+Package: mgmt
+Architecture: any
+Depends: ${shlibs:Depends}, ${misc:Depends}, packagekit
+Suggests:      graphviz
+Description: mgmt: next generation config management!
+ The mgmt tool is a next generation config management prototype. It's
+ not yet ready for production, but we hope to get there soon. Get
+ involved today!

debian/copyright

@@ -0,0 +1,33 @@
+Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: mgmt
+Source: <https://github.com/purpleidea/mgmt>
+
+Files: *
+Copyright: Copyright (C) 2013-2024+ James Shubin and the project contributors
+License: GPL-3.0
+
+License: GPL-3.0
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+  Additional permission under GNU GPL version 3 section 7
+
+  If you modify this program, or any covered work, by linking or combining it
+  with embedded mcl code and modules (and that the embedded mcl code and
+  modules which link with this program, contain a copy of their source code in
+  the authoritative form) containing parts covered by the terms of any other
+  license, the licensors of this program grant you additional permission to
+  convey the resulting work. Furthermore, the licensors of this program grant
+  the original author, James Shubin, additional permission to update this
+  additional permission if he deems it necessary to achieve the goals of this
+  additional permission.

debian/mgmt.docs

@@ -0,0 +1,11 @@
+AUTHORS
+COPYING
+COPYRIGHT
+README.md
+THANKS
+TODO.md
+docs
+examples
+misc/bashrc.sh
+misc/delta-cpu.sh
+misc/mgmt.service

debian/mgmt.install

@@ -0,0 +1,2 @@
+mgmt usr/bin
+misc/mgmt.service /lib/systemd/system

debian/rules

@@ -0,0 +1,15 @@
+#!/usr/bin/make -f
+
+export DH_OPTIONS
+export DH_GOPKG := mgmt
+export DH_GOLANG_INSTALL_ALL := 1
+unexport GOROOT
+
+override_dh_auto_build:
+	make build
+
+override_dh_auto_test:
+	@echo "Tests are disabled for now"
+
+%:
+	dh $@ --with=systemd

doc.go

@@ -0,0 +1,31 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+// Package main provides the main entrypoint for using the `mgmt` software.
+package main

docker/Dockerfile

@@ -0,0 +1,22 @@
+FROM golang:1.20
+
+MAINTAINER Michał Czeraszkiewicz <contact@czerasz.com>
+
+# Set the reset cache variable
+# Read more here: http://czerasz.com/2014/11/13/docker-tip-and-tricks/#use-refreshedat-variable-for-better-cache-control
+ENV REFRESHED_AT 2020-09-23
+
+# Update the package list to be able to use required packages
+RUN apt-get update
+
+# Change the working directory
+WORKDIR /go/src/mgmt
+
+# Copy all the files to the working directory
+COPY . /go/src/mgmt
+
+# Install dependencies
+RUN make deps
+
+# Build the binary
+RUN make build

docker/Dockerfile-fedora.build

@@ -0,0 +1,20 @@
+FROM fedora:38
+LABEL org.opencontainers.image.authors="laurent.indermuehle@pm.me"
+
+ENV GOPATH=/root/gopath
+ENV PATH=/root/gopath/bin:/usr/local/sbin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/go/bin:/usr/local/bin
+ENV LD_LIBRARY_PATH=/usr/lib64
+ENV PKG_CONFIG_PATH=/usr/lib64/pkgconfig
+
+# This forces make-deps.sh to install Ragel 6.1 instead of 7.0
+ENV DOCKER=true
+
+RUN dnf -y install wget unzip git make which gcc gcc-c++ ruby golang
+
+RUN mkdir -p $GOPATH/src/github.com/purpleidea
+WORKDIR $GOPATH/src/github.com/purpleidea
+RUN git clone --recursive https://github.com/purpleidea/mgmt mgmt
+WORKDIR $GOPATH/src/github.com/purpleidea/mgmt
+RUN make deps
+RUN make build
+CMD ["/bin/bash"]

docker/Dockerfile.build

@@ -0,0 +1,12 @@
+FROM centos:7
+MAINTAINER Karim Boumedhel <karimboumedhel@gmail.com>
+
+ENV GOPATH=/root/gopath
+ENV PATH=/opt/rh/rh-ruby22/root/usr/bin:/root/gopath/bin:/usr/local/sbin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/go/bin
+ENV LD_LIBRARY_PATH=/opt/rh/rh-ruby22/root/usr/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}
+ENV PKG_CONFIG_PATH=/opt/rh/rh-ruby22/root/usr/lib64/pkgconfig${PKG_CONFIG_PATH:+:${PKG_CONFIG_PATH}}
+
+RUN yum -y install epel-release wget unzip git make which centos-release-scl gcc && sed -i "s/enabled=0/enabled=1/" /etc/yum.repos.d/epel-testing.repo && yum -y install rh-ruby22 && wget -O /opt/go1.20.11.linux-amd64.tar.gz https://storage.googleapis.com/golang/go1.20.11.linux-amd64.tar.gz && tar -C /usr/local -xzf /opt/go1.20.11.linux-amd64.tar.gz
+RUN mkdir -p $GOPATH/src/github.com/purpleidea && cd $GOPATH/src/github.com/purpleidea && git clone --recursive https://github.com/purpleidea/mgmt
+RUN go get -u gopkg.in/alecthomas/gometalinter.v1 && cd $GOPATH/src/github.com/purpleidea/mgmt && make deps && make build
+CMD ["/bin/bash"]

docker/Dockerfile.development

@@ -0,0 +1,31 @@
+FROM golang:1.20
+
+MAINTAINER Michał Czeraszkiewicz <contact@czerasz.com>
+
+# Set the reset cache variable
+# Read more here: http://czerasz.com/2014/11/13/docker-tip-and-tricks/#use-refreshedat-variable-for-better-cache-control
+ENV REFRESHED_AT 2019-02-06
+
+RUN apt-get update
+
+# Setup User to match Host User
+# Give the nre user superuser permissions
+ARG USER_ID=1000
+ARG GROUP_ID=1000
+ARG USER_NAME=mgmt
+ARG GROUP_NAME=$USER_NAME
+RUN groupadd --gid $GROUP_ID $GROUP_NAME && \
+	useradd --create-home --home /home/$USER_NAME --uid ${USER_ID} --gid $GROUP_NAME --groups sudo $USER_NAME && \
+	echo "$USER_NAME ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+
+# Copy all the files to the working directory
+COPY . /home/$USER_NAME/mgmt
+
+# Change working directory
+WORKDIR /home/$USER_NAME/mgmt
+
+# Install dependencies
+RUN make deps
+
+# Change user
+USER ${USER_NAME}

docker/Dockerfile.static

@@ -0,0 +1,9 @@
+FROM centos:7
+MAINTAINER Karim Boumedhel <karimboumedhel@gmail.com>
+
+RUN yum -y install augeas-libs libvirt-libs && yum clean all
+ADD mgmt /usr/bin
+RUN chmod 700 /usr/bin/mgmt
+
+ENTRYPOINT ["/usr/bin/mgmt"]
+CMD ["-h"]

docker/scripts/build

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+script_directory="$( cd "$( dirname "$0" )" && pwd )"
+project_directory=$script_directory/../..
+
+# Specify the Docker image name
+image_name='purpleidea/mgmt'
+
+# Build the image which contains the compiled binary
+docker build -t $image_name \
+	--file=$project_directory/docker/Dockerfile $project_directory
+
+# Remove the container if it already exists
+docker rm -f mgmt-export 2> /dev/null
+
+# Start the container in background so we can "copy out" the binary
+docker run -d --name=mgmt-export $image_name bash -c 'while true; sleep 1000; done'
+
+# Remove the current binary
+rm $project_directory/mgmt 2> /dev/null
+
+# Get the binary from the container
+docker cp mgmt-export:/go/src/mgmt/mgmt $project_directory/mgmt
+
+# Remove the container
+docker rm -f mgmt-export 2> /dev/null

docker/scripts/build-development

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# Stop on any error
+set -e
+
+script_directory="$( cd "$( dirname "$0" )" && pwd )"
+project_directory=$script_directory/../..
+
+# Specify the Docker image name
+image_name='purpleidea/mgmt:development'
+
+# Build the image
+docker build -t $image_name \
+	--file=$project_directory/docker/Dockerfile.development $project_directory

docker/scripts/exec-development

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# runs command provided as argument inside a development (Linux) Docker container
+
+# Stop on any error
+set -e
+
+script_directory="$( cd "$( dirname "$0" )" && pwd )"
+project_directory=$script_directory/../..
+
+# Specify the Docker image name
+image_name='purpleidea/mgmt:development'
+
+# Run container in development mode
+docker run --rm --name=mgm_development --user=mgmt \
+	-v "$project_directory:/go/src/github.com/purpleidea/mgmt/" \
+	-w /go/src/github.com/purpleidea/mgmt/ \
+	-it "$image_name" /bin/bash -c "$*"

docker/scripts/run-development

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# Stop on any error
+set -e
+
+script_directory="$( cd "$( dirname "$0" )" && pwd )"
+project_directory=$script_directory/../..
+
+# Specify the Docker image name
+image_name='purpleidea/mgmt:development'
+
+# Run container in development mode
+docker run --rm --name=mgm_development --user=mgmt \
+	-v $project_directory:/home/mgmt/mgmt \
+	-it $image_name bash

docs/.gitignore

@@ -0,0 +1,2 @@
+mgmt-documentation.pdf
+_build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = mgmt
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,158 @@
+# -*- coding: utf-8 -*-
+#
+# mgmt documentation build configuration file, created by
+# sphinx-quickstart on Wed Feb 15 21:34:09 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+from recommonmark.parser import CommonMarkParser
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+
+source_parsers = {
+        '.md': CommonMarkParser,
+}
+
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'mgmt'
+copyright = u'2013-2024+ James Shubin and the project contributors'
+author = u'James Shubin'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u''
+# The full version, including alpha/beta/rc tags.
+release = u''
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+#html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'mgmtdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'mgmt.tex', u'mgmt Documentation',
+     u'James Shubin', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'mgmt', u'mgmt Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'mgmt', u'mgmt Documentation',
+     author, 'mgmt', 'A next generation config management prototype!',
+     'Miscellaneous'),
+]

docs/development.md

@@ -0,0 +1,162 @@
+# Development
+
+This document contains some additional information and help regarding
+developing `mgmt`. Useful tools, conventions, etc.
+
+Be sure to read [quick start guide](quick-start-guide.md) first.
+
+## Vagrant
+
+If you would like to avoid doing the above steps manually, we have prepared a
+[Vagrant](https://www.vagrantup.com/) environment for your convenience. From the
+project directory, run a `vagrant up`, and then a `vagrant status`. From there,
+you can `vagrant ssh` into the `mgmt` machine. The `MOTD` will explain the rest.
+This environment isn't commonly used by the `mgmt` developers, so it might not
+be working properly.
+
+## Using Docker
+
+Alternatively, you can check out the [docker-guide](docker-guide.md) in order to
+develop or deploy using docker. This method is not endorsed or supported, so use
+at your own risk, as it might not be working properly.
+
+## Information about dependencies
+
+Software projects have a few different kinds of dependencies. There are _build_
+dependencies, _runtime_ dependencies, and additionally, a few extra dependencies
+required for running the _test_ suite.
+
+### Build
+
+* `golang` 1.20 or higher (required, available in some distros and distributed
+as a binary officially by [golang.org](https://golang.org/dl/))
+
+### Runtime
+
+A relatively modern GNU/Linux system should be able to run `mgmt` without any
+problems. Since `mgmt` runs as a single statically compiled binary, all of the
+library dependencies are included. It is expected, that certain advanced
+resources require host specific facilities to work. These requirements are
+listed below:
+
+| Resource | Dependency        | Version                     | Check version with                                        |
+|----------|-------------------|-----------------------------|-----------------------------------------------------------|
+| augeas   | augeas-devel      | `augeas 1.6` or greater     | `dnf info augeas-devel` or `apt-cache show libaugeas-dev` |
+| file     | inotify           | `Linux 2.6.27` or greater   | `uname -a`                                                |
+| hostname | systemd-hostnamed | `systemd 25` or greater     | `systemctl --version`                                     |
+| nspawn   | systemd-nspawn    | `systemd ???` or greater    | `systemctl --version`                                     |
+| pkg      | packagekitd       | `packagekit 1.x` or greater | `pkcon --version`                                         |
+| svc      | systemd           | `systemd ???` or greater    | `systemctl --version`                                     |
+| virt     | libvirt-devel     | `libvirt 1.2.0` or greater  | `dnf info libvirt-devel` or `apt-cache show libvirt-dev`  |
+| virt     | libvirtd          | `libvirt 1.2.0` or greater  | `libvirtd --version`                                      |
+
+For building a visual representation of the graph, `graphviz` is required.
+
+To build `mgmt` without augeas support please run:
+`GOTAGS='noaugeas' make build`
+
+To build `mgmt` without libvirt support please run:
+`GOTAGS='novirt' make build`
+
+To build `mgmt` without docker support please run:
+`GOTAGS='nodocker' make build`
+
+To build `mgmt` without augeas, libvirt or docker support please run:
+`GOTAGS='noaugeas novirt nodocker' make build`
+
+## OSX/macOS/Darwin development
+
+Developing and running `mgmt` on macOS is currently not supported (but not
+discouraged either). Meaning it might work but in the case it doesn't you would
+have to provide your own patches to fix problems (the project maintainer and
+community are glad to assist where needed).
+
+There are currently some issues that make `mgmt` less suitable to run for
+provisioning macOS. But as a client to provision remote servers it should run
+fine.
+
+Since the primary supported systems are Linux and these are the environments
+tested, it is wise to run these suites during macOS development as well. To ease
+this, Docker can be leveraged ([Docker for Mac](https://docs.docker.com/docker-for-mac/)).
+
+Before running any of the commands below create the development Docker image:
+
+```
+docker/scripts/build-development
+```
+
+This image requires updating every time dependencies (`make-deps.sh`) changes.
+
+Then to run the test suite:
+
+```
+docker run --rm -ti \
+	-v $PWD:/go/src/github.com/purpleidea/mgmt/ \
+	-w /go/src/github.com/purpleidea/mgmt/ \
+	purpleidea/mgmt:development \
+	make test
+```
+
+For convenience this command is wrapped in `docker/scripts/exec-development`.
+
+Basically any command can be executed this way. Because the repository source is
+mounted into the Docker container invocation will be quick and allow rapid
+testing, for example:
+
+```
+docker/scripts/exec-development test/test-shell.sh load0.sh
+```
+
+Other examples:
+
+```
+docker/scripts/exec-development make build
+docker/scripts/exec-development ./mgmt run --tmp-prefix lang examples/lang/load0.mcl
+```
+
+Be advised that this method is not supported and it might not be working
+properly.
+
+## Testing
+
+This project has both unit tests in the form of golang tests and integration
+tests using shell scripting.
+
+Native golang tests are preferred over tests written in our shell testing
+framework. Please see [https://golang.org/pkg/testing/](https://golang.org/pkg/testing/)
+for more information.
+
+To run all tests:
+
+```
+make test
+```
+
+There is a library of quick and small integration tests for the language and
+YAML related things, check out [`test/shell/`](/test/shell). Adding a test is as
+easy as copying one of the files in [`test/shell/`](/test/shell) and adapting
+it.
+
+This test suite won't run by default (unless when on CI server) and needs to be
+called explictly using:
+
+```
+make test-shell
+```
+
+Or run an individual shell test using:
+
+```
+make test-shell-load0
+```
+
+Tip: you can use TAB completion with `make` to quickly get a list of possible
+individual tests to run.
+
+## Tools, integrations, IDE's etc
+
+### IDE/Editor support
+
+* Emacs: see `misc/emacs/`
+* [Textmate](https://github.com/aequitas/mgmt.tmbundle)
+* [VSCode](https://github.com/aequitas/mgmt.vscode)

docs/documentation.md

@@ -0,0 +1,454 @@
+# General documentation
+
+## Overview
+
+The `mgmt` tool is a next generation config management prototype. It's not yet
+ready for production, but we hope to get there soon. Get involved today!
+
+## Project Description
+
+The mgmt tool is a distributed, event driven, config management tool, that
+supports parallel execution, and librarification to be used as the management
+foundation in and for, new and existing software.
+
+For more information, you may like to read some blog posts from the author:
+
+* [Next generation config mgmt](https://purpleidea.com/blog/2016/01/18/next-generation-configuration-mgmt/)
+* [Automatic edges in mgmt](https://purpleidea.com/blog/2016/03/14/automatic-edges-in-mgmt/)
+* [Automatic grouping in mgmt](https://purpleidea.com/blog/2016/03/30/automatic-grouping-in-mgmt/)
+* [Automatic clustering in mgmt](https://purpleidea.com/blog/2016/06/20/automatic-clustering-in-mgmt/)
+* [Remote execution in mgmt](https://purpleidea.com/blog/2016/10/07/remote-execution-in-mgmt/)
+* [Send/Recv in mgmt](https://purpleidea.com/blog/2016/12/07/sendrecv-in-mgmt/)
+* [Metaparameters in mgmt](https://purpleidea.com/blog/2017/03/01/metaparameters-in-mgmt/)
+
+There is also an [introductory video](https://www.youtube.com/watch?v=LkEtBVLfygE&html5=1)
+available. Older videos and other material [is available](on-the-web.md).
+
+## Setup
+
+You'll probably want to read the [quick start guide](quick-start-guide.md) to
+get going.
+
+## Features
+
+This section details the numerous features of mgmt and some caveats you might
+need to be aware of.
+
+### Autoedges
+
+Automatic edges, or AutoEdges, is the mechanism in mgmt by which it will
+automatically create dependencies for you between resources. For example,
+since mgmt can discover which files are installed by a package it will
+automatically ensure that any file resource you declare that matches a
+file installed by your package resource will only be processed after the
+package is installed.
+
+#### Controlling autoedges
+
+Though autoedges is likely to be very helpful and avoid you having to declare
+all dependencies explicitly, there are cases where this behaviour is
+undesirable.
+
+Some distributions allow package installations to automatically start the
+service they ship. This can be problematic in the case of packages like MySQL
+as there are configuration options that need to be set before MySQL is ever
+started for the first time (or you'll need to wipe the data directory). In
+order to handle this situation you can disable autoedges per resource and
+explicitly declare that you want `my.cnf` to be written to disk before the
+installation of the `mysql-server` package.
+
+You can disable autoedges for a resource by setting the `autoedge` key on
+the meta attributes of that resource to `false`.
+
+#### Blog post
+
+You can read the introductory blog post about this topic here:
+[https://purpleidea.com/blog/2016/03/14/automatic-edges-in-mgmt/](https://purpleidea.com/blog/2016/03/14/automatic-edges-in-mgmt/)
+
+### Autogrouping
+
+Automatic grouping or AutoGroup is the mechanism in mgmt by which it will
+automatically group multiple resource vertices into a single one. This is
+particularly useful for grouping multiple package resources into a single
+resource, since the multiple installations can happen together in a single
+transaction, which saves a lot of time because package resources typically have
+a large fixed cost to running (downloading and verifying the package repo) and
+if they are grouped they share this fixed cost. This grouping feature can be
+used for other use cases too.
+
+You can disable autogrouping for a resource by setting the `autogroup` key on
+the meta attributes of that resource to `false`.
+
+#### Blog post
+
+You can read the introductory blog post about this topic here:
+[https://purpleidea.com/blog/2016/03/30/automatic-grouping-in-mgmt/](https://purpleidea.com/blog/2016/03/30/automatic-grouping-in-mgmt/)
+
+### Automatic clustering
+
+Automatic clustering is a feature by which mgmt automatically builds, scales,
+and manages the embedded etcd cluster which is compiled into mgmt itself. It is
+quite helpful for rapidly bootstrapping clusters and avoiding the extra work to
+setup etcd.
+
+If you prefer to avoid this feature. you can always opt to use an existing etcd
+cluster that is managed separately from mgmt by pointing your mgmt agents at it
+with the `--seeds` variable.
+
+#### Blog post
+
+You can read the introductory blog post about this topic here:
+[https://purpleidea.com/blog/2016/06/20/automatic-clustering-in-mgmt/](https://purpleidea.com/blog/2016/06/20/automatic-clustering-in-mgmt/)
+
+### Remote ("agent-less") mode
+
+Remote mode is a special mode that lets you kick off mgmt runs on one or more
+remote machines which are only accessible via SSH. In this mode the initiating
+host connects over SSH, copies over the `mgmt` binary, opens an SSH tunnel, and
+runs the remote program while simultaneously passing the etcd traffic back
+through the tunnel so that the initiators etcd cluster can be used to exchange
+resource data.
+
+The interesting benefit of this architecture is that multiple hosts which can't
+connect directly use the initiator to pass the important traffic through to each
+other. Once the cluster has converged all the remote programs can shutdown
+leaving no residual agent.
+
+This mode can also be useful for bootstrapping a new host where you'd like to
+have the service run continuously and as part of an mgmt cluster normally.
+
+In particular, when combined with the `--converged-timeout` parameter, the
+entire set of running mgmt agents will need to all simultaneously converge for
+the group to exit. This is particularly useful for bootstrapping new clusters
+which need to exchange information that is only available at run time.
+
+This existed in earlier versions of mgmt as a `--remote` option, but it has been
+removed and is being ported to a more powerful variant where you can remote
+execute via a `remote` resource.
+
+#### Blog post
+
+You can read the introductory blog post about this topic here:
+[https://purpleidea.com/blog/2016/10/07/remote-execution-in-mgmt/](https://purpleidea.com/blog/2016/10/07/remote-execution-in-mgmt/)
+
+## Reference
+
+Please note that there are a number of undocumented options. For more
+information on these options, please view the source at:
+[https://github.com/purpleidea/mgmt/](https://github.com/purpleidea/mgmt/).
+If you feel that a well used option needs documenting here, please patch it!
+
+### Overview of reference
+
+* [Meta parameters](#meta-parameters): List of available resource meta parameters.
+* [Lang metadata file](#lang-metadata-file): Lang metadata file format.
+* [Graph definition file](#graph-definition-file): Main graph definition file.
+* [Command line](#command-line): Command line parameters.
+* [Compilation options](#compilation-options): Compilation options.
+
+### Meta parameters
+
+These meta parameters are special parameters (or properties) which can apply to
+any resource. The usefulness of doing so will depend on the particular meta
+parameter and resource combination.
+
+#### AutoEdge
+
+Boolean. Should we generate auto edges for this resource?
+
+#### AutoGroup
+
+Boolean. Should we attempt to automatically group this resource with others?
+
+#### Noop
+
+Boolean. Should the Apply portion of the CheckApply method of the resource
+make any changes? Noop is a concatenation of no-operation.
+
+#### Retry
+
+Integer. The number of times to retry running the resource on error. Use -1 for
+infinite. This currently applies for both the Watch operation (which can fail)
+and for the CheckApply operation. While they could have separate values, I've
+decided to use the same ones for both until there's a proper reason to want to
+do something differently for the Watch errors.
+
+#### Delay
+
+Integer. Number of milliseconds to wait between retries. The same value is
+shared between the Watch and CheckApply retries. This currently applies for both
+the Watch operation (which can fail) and for the CheckApply operation. While
+they could have separate values, I've decided to use the same ones for both
+until there's a proper reason to want to do something differently for the Watch
+errors.
+
+#### Poll
+
+Integer. Number of seconds to wait between `CheckApply` checks. If this is
+greater than zero, then the standard event based `Watch` mechanism for this
+resource is replaced with a simple polling mechanism. In general, this is not
+recommended, unless you have a very good reason for doing so.
+
+Please keep in mind that if you have a resource which changes every `I` seconds,
+and you poll it every `J` seconds, and you've asked for a converged timeout of
+`K` seconds, and `I <= J <= K`, then your graph will likely never converge.
+
+When polling, the system detects that a resource is not converged if its
+`CheckApply` method returns false. This allows a resource which changes every
+`I` seconds, and which is polled every `J` seconds, and with a converged timeout
+of `K` seconds to still converge when `J <= K`, as long as `I > J || I > K`,
+which is another way of saying that if the resource finally settles down to give
+the graph enough time, it can probably converge.
+
+#### Limit
+
+Float. Maximum rate of `CheckApply` runs started per second. Useful to limit
+an especially _eventful_ process from causing excessive checks to run. This
+defaults to `+Infinity` which adds no limiting. If you change this value, you
+will also need to change the `Burst` value to a non-zero value. Please see the
+[rate](https://godoc.org/golang.org/x/time/rate) package for more information.
+
+#### Burst
+
+Integer. Burst is the maximum number of runs which can happen without invoking
+the rate limiter as designated by the `Limit` value. If the `Limit` is not set
+to `+Infinity`, this must be a non-zero value. Please see the
+[rate](https://godoc.org/golang.org/x/time/rate) package for more information.
+
+#### Sema
+
+List of string ids. Sema is a P/V style counting semaphore which can be used to
+limit parallelism during the CheckApply phase of resource execution. Each
+resource can have `N` different semaphores which share a graph global namespace.
+Each semaphore has a maximum count associated with it. The default value of the
+size is 1 (one) if size is unspecified. Each string id is the unique id of the
+semaphore. If the id contains a trailing colon (:) followed by a positive
+integer, then that value is the max size for that semaphore. Valid semaphore
+id's include: `some_id`, `hello:42`, `not:smart:4` and `:13`. It is expected
+that the last bare example be only used by the engine to add a global semaphore.
+
+#### Rewatch
+
+Boolean. Rewatch specifies whether we re-run the Watch worker during a graph
+swap if it has errored. When doing a graph compare to swap the graphs, if this
+is true, and this particular worker has errored, then we'll remove it and add it
+back as a new vertex, thus causing it to run again. This is different from the
+`Retry` metaparam which applies during the normal execution. It is only when
+this is exhausted that we're in permanent worker failure, and only then can we
+rely on this metaparam.
+
+#### Realize
+
+Boolean. Realize ensures that the resource is guaranteed to converge at least
+once before a potential graph swap removes or changes it. This guarantee is
+useful for fast changing graphs, to ensure that the brief creation of a resource
+is seen. This guarantee does not prevent against the engine quitting normally,
+and it can't guarantee it if the resource is blocked because of a failed
+pre-requisite resource.
+*XXX: This is currently not implemented!*
+
+#### Reverse
+
+Boolean. Reverse is a property that some resources can implement that specifies
+that some "reverse" operation should happen when that resource "disappears". A
+disappearance happens when a resource is defined in one instance of the graph,
+and is gone in the subsequent one. This disappearance can happen if it was
+previously in an if statement that then becomes false.
+
+This is helpful for building robust programs with the engine. The engine adds a
+"reversed" resource to that subsequent graph to accomplish the desired "reverse"
+mechanics. The specifics of what this entails is a property of the particular
+resource that is being "reversed".
+
+It might be wise to combine the use of this meta parameter with the use of the
+`realize` meta parameter to ensure that your reversed resource actually runs at
+least once, if there's a chance that it might be gone for a while.
+
+### Lang metadata file
+
+Any module *must* have a metadata file in its root. It must be named
+`metadata.yaml`, even if it's empty. You can specify zero or more values in yaml
+format which can change how your module behaves, and where the `mcl` language
+looks for code and other files. The most important top level keys are: `main`,
+`path`, `files`, and `license`.
+
+#### Main
+
+The `main` key points to the default entry point of your code. It must be a
+relative path if specified. If it's empty it defaults to `main.mcl`. It should
+generally not be changed. It is sometimes set to `main/main.mcl` if you'd like
+your modules code out of the root and into a child directory for cases where you
+don't plan on having a lot deeper imports relative to `main.mcl` and all those
+files would clutter things up.
+
+#### Path
+
+The `path` key specifies the modules import search directory to use for this
+module. You can specify this if you'd like to vendor something for your module.
+In general, if you use it, please use the convention: `path/`. If it's not
+specified, you will default to the parent modules directory.
+
+#### Files
+
+The `files` key specifies some additional files that will get included in your
+deploy. It defaults to `files/`.
+
+#### License
+
+The `license` key allows you to specify a license for the module. Please specify
+one so that everyone can enjoy your code! Use a "short license identifier", like
+`LGPLv3+`, or `MIT`. The former is a safe choice if you're not sure what to use.
+
+### Graph definition file
+
+graph.yaml is the compiled graph definition file. The format is currently
+undocumented, but by looking through the [examples/](https://github.com/purpleidea/mgmt/tree/master/examples/yaml/)
+you can probably figure out most of it, as it's fairly intuitive. It's not
+recommended that you use this, since it's preferable to write code in the
+[mcl language](language-guide.md) front-end.
+
+### Command line
+
+The main interface to the `mgmt` tool is the command line. For the most recent
+documentation, please run `mgmt --help`.
+
+#### `--converged-timeout <seconds>`
+
+Exit if the machine has converged for approximately this many seconds.
+
+#### `--max-runtime <seconds>`
+
+Exit when the agent has run for approximately this many seconds. This is not
+generally recommended, but may be useful for users who know what they're doing.
+
+#### `--noop`
+
+Globally force all resources into no-op mode. This also disables the export to
+etcd functionality, but does not disable resource collection, however all
+resources that are collected will have their individual noop settings set.
+
+#### `--sema <size>`
+
+Globally add a counting semaphore of this size to each resource in the graph.
+The semaphore will get given an id of `:size`. In other words if you specify a
+size of 42, you can expect a semaphore if named: `:42`. It is expected that
+consumers of the semaphore metaparameter always include a prefix to avoid a
+collision with this globally defined semaphore. The size value must be greater
+than zero at this time. The traditional non-parallel execution found in config
+management tools such as `Puppet` can be obtained with `--sema 1`.
+
+#### `--ssh-priv-id-rsa`
+
+Specify the path for finding SSH keys. This defaults to `~/.ssh/id_rsa`. To
+never use this method of authentication, set this to the empty string.
+
+#### `--prefix <path>`
+
+Specify a path to a custom working directory prefix. This directory will get
+created if it does not exist. This usually defaults to `/var/lib/mgmt/`. This
+can't be combined with the `--tmp-prefix` option. It can be combined with the
+`--allow-tmp-prefix` option.
+
+#### `--tmp-prefix`
+
+If this option is specified, a temporary prefix will be used instead of the
+default prefix. This can't be combined with the `--prefix` option.
+
+#### `--allow-tmp-prefix`
+
+If this option is specified, we will attempt to fall back to a temporary prefix
+if the primary prefix couldn't be created. This is useful for avoiding failures
+in environments where the primary prefix may or may not be available, but you'd
+like to try. The canonical example is when running `mgmt` with remote execution
+there might be a cached copy of the binary in the primary prefix, but if there's
+no binary available continue working in a temporary directory to avoid failure.
+
+### Compilation options
+
+You can control some compilation variables by using environment variables.
+
+#### Disable libvirt support
+
+If you wish to compile mgmt without libvirt, you can use the following command:
+
+```
+GOTAGS=novirt make build
+```
+
+#### Disable augeas support
+
+If you wish to compile mgmt without augeas support, you can use the following
+command:
+
+```
+GOTAGS=noaugeas make build
+```
+
+#### Disable docker support
+
+If you wish to compile mgmt without docker support, you can use the following
+command:
+
+```
+GOTAGS=nodocker make build
+```
+
+#### Combining compile-time flags
+
+You can combine multiple tags by using a space-separated list:
+
+```
+GOTAGS="noaugeas novirt nodocker" make build
+```
+
+## Examples
+
+For example configurations, please consult the [examples/](https://github.com/purpleidea/mgmt/tree/master/examples)
+directory in the git source repository. It is available from:
+
+[https://github.com/purpleidea/mgmt/tree/master/examples](https://github.com/purpleidea/mgmt/tree/master/examples)
+
+### Systemd:
+
+See [`misc/mgmt.service`](misc/mgmt.service) for a sample systemd unit file.
+This unit file is part of the RPM.
+
+To specify your custom options for `mgmt` on a systemd distro:
+
+```bash
+sudo mkdir -p /etc/systemd/system/mgmt.service.d/
+
+cat > /etc/systemd/system/mgmt.service.d/env.conf <<EOF
+# Environment variables:
+MGMT_SEEDS=http://127.0.0.1:2379
+MGMT_CONVERGED_TIMEOUT=-1
+MGMT_MAX_RUNTIME=0
+
+# Other CLI options if necessary.
+#OPTS="--max-runtime=0"
+EOF
+
+sudo systemctl daemon-reload
+```
+
+## Development
+
+This is a project that I started in my free time in 2013. Development is driven
+by all of our collective patches! Dive right in, and start hacking!
+Please contact me if you'd like to invite me to speak about this at your event.
+
+You can follow along [on my technical blog](https://purpleidea.com/blog/).
+
+To report any bugs, please file a ticket at: [https://github.com/purpleidea/mgmt/issues](https://github.com/purpleidea/mgmt/issues).
+
+## Authors
+
+Copyright (C) 2013-2024+ James Shubin and the project contributors
+
+Please see the
+[AUTHORS](https://github.com/purpleidea/mgmt/tree/master/AUTHORS) file
+for more information.
+
+* [github](https://github.com/purpleidea/)
+* [&#64;purpleidea](https://twitter.com/#!/purpleidea)
+* [https://purpleidea.com/](https://purpleidea.com/)

docs/faq.md

@@ -0,0 +1,470 @@
+## Frequently asked questions
+
+(Send your questions as a patch to this FAQ! I'll review it, merge it, and
+respond by commit with the answer.)
+
+### Why did you start this project?
+
+I wanted a next generation config management solution that didn't have all of
+the design flaws or limitations that the current generation of tools do, and no
+tool existed!
+
+### Why did you choose `golang` for the project?
+
+When I started working on the project, I needed to choose a language that
+already had an implementation of a distributed consensus algorithm available.
+That meant [Paxos](https://en.wikipedia.org/wiki/Paxos_(computer_science)) or
+[Raft](https://en.wikipedia.org/wiki/Raft_(computer_science)). Golang was one
+language that actually had two different Raft implementations, `etcd`, and
+`consul`. Other design requirements included something that was reasonably fast,
+typed and memory-safe, and suited for systems engineering. After a reasonably
+extensive search, I chose `golang`. I think it was the right decision. There are
+a number of other features of the language which helped influence the decision.
+
+### How do I contribute to the project if I don't know `golang`?
+
+There are many different ways you can contribute to the project. They can be
+broadly divided into two main categories:
+
+1. With contributions written in `golang`
+2. With contributions _not_ written in `golang`
+
+If you do not know `golang`, and have no desire to learn, you can still
+contribute to mgmt by using it, testing it, writing docs, or even just by
+telling your friends about it. If you don't mind some coding, learning about the
+[mgmt language](https://purpleidea.com/blog/2018/02/05/mgmt-configuration-language/)
+might be an enjoyable experience for you. It is a small [DSL](https://en.wikipedia.org/wiki/Domain-specific_language)
+and not a general purpose programming language, and you might find it more fun
+than what you're typically used to. One of the reasons the mgmt author got into
+writing automation modules, was because he found it much more fun to build with
+a higher level DSL, than in a general purpose programming language.
+
+If you do not know `golang`, and would like to learn, are a beginner and want to
+improve your skills, or want to gain some great interdisciplinary systems
+engineering knowledge around a cool automation project, we're happy to mentor
+you. Here are some pre-requisites steps which we recommend:
+
+1. Make sure you have a somewhat recent GNU/Linux environment to hack on. A
+recent [Fedora](https://getfedora.org/) or [Debian](https://www.debian.org/)
+environment is recommended. Developing, testing, and contributing on `macOS` or
+`Windows` will be either more difficult or impossible.
+2. Ensure that you're mildly comfortable with the basics of using `git`. You can
+find a number of tutorials online.
+3. Spend between four to six hours with the [golang tour](https://tour.golang.org/).
+Skip over the longer problems, but try and get a solid overview of everything.
+If you forget something, you can always go back and repeat those parts.
+4. Connect to our [#mgmtconfig](https://web.libera.chat/?channels=#mgmtconfig)
+IRC channel on the [Libera.Chat](https://libera.chat/) network. You can use any
+IRC client that you'd like, but the [hosted web portal](https://web.libera.chat/?channels=#mgmtconfig)
+will suffice if you don't know what else to use. [Here are a few suggestions for
+alternative clients.](https://libera.chat/guides/clients)
+5. Now it's time to try and starting writing a patch! We have tagged a bunch of
+[open issues as #mgmtlove](https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%3Amgmtlove)
+for new users to have somewhere to get involved. Look through them to see if
+something interests you. If you find one, let us know you're working on it by
+leaving a comment in the ticket. We'll be around to answer questions in the IRC
+channel, and to create new issues if there wasn't something that fit your
+interests. When you submit a patch, we'll review it and give you some feedback.
+Over time, we hope you'll learn a lot while supporting the project! Now get
+hacking!
+
+### Is this project ready for production?
+
+It's getting pretty close. I'm able to write modules for it now!
+
+Compared to some existing automation tools out there, mgmt is a relatively new
+project. It is probably not as feature complete as some other software, but it
+also offers a number of features which are not currently available elsewhere.
+
+Because we have not released a `1.0` release yet, we are not guaranteeing
+stability of the internal or external API's. We only change them if it's really
+necessary, and we don't expect anything particularly drastic to occur. We would
+expect it to be relatively easy to adapt your code if such changes happened.
+
+As with all software, bugs can occur, and while we make no guarantees of being
+bug-free, there are a number of things we've done to reduce the chances of one
+causing you trouble:
+
+1. Our software is written in golang, which is a memory-safe language, and which
+is known to reduce or eliminate entire classes of bugs.
+2. We have a test suite which we run on every commit, and every 24 hours. If you
+have a particular case that you'd like to test, you are welcome to add it in!
+3. The mgmt language itself offers a number of safety features. You can
+[read about them in the introductory blog post](https://purpleidea.com/blog/2018/02/05/mgmt-configuration-language/).
+
+Having said all this, as with all software, there are still missing features
+which some users might want in their production environments. We're working hard
+to get all of those implemented, but we hope that you'll get involved and help
+us finish off the ones that are most important to you. We are happy to mentor
+new contributors, and have even [tagged](https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%3Amgmtlove)
+a number of issues if you need help getting started.
+
+Some of the current limitations include:
+
+* Auth hasn't been implemented yet, so you should only use it in trusted
+environments (not on publicly accessible networks) for now.
+* The number of built-in core functions is still small. You may encounter
+scenarios where you're missing a function. The good news is that it's relatively
+easy to add this missing functionality yourself. In time, with your help, the
+list will grow!
+* Large file distribution is not yet implemented. You might want a scenario
+where mgmt is used to distribute large files (such as `.iso` images) throughout
+your cluster. While this isn't a common use-case, it won't be possible until
+someone wants to write the patch. (Mentoring available!) You can workaround this
+easily by storing those files on a separate fileserver for the interim.
+* There isn't an ecosystem of community `modules` yet. We've got this on our
+roadmap, so please stay tuned!
+
+We hope you'll participate as an early adopter. Every additional pair of helping
+hands gets us all there faster! It's quite possible to use this to build useful
+automation today, and we hope you'll start getting familiar with the software.
+
+### Why did you use etcd? What about consul?
+
+Etcd and consul are both written in golang, which made them the top two
+contenders for my prototype. Ultimately a choice had to be made, and etcd was
+chosen, but it was also somewhat arbitrary. If there is available interest,
+good reasoning, *and* patches, then we would consider either switching or
+supporting both, but this is not a high priority at this time.
+
+### Can I use an existing etcd cluster instead of the automatic embedded servers?
+
+Yes, it's possible to use an existing etcd cluster instead of the automatic,
+elastic embedded etcd servers. To do so, simply point to the cluster with the
+`--seeds` variable, the same way you would if you were seeding a new member to
+an existing mgmt cluster.
+
+The downside to this approach is that you won't benefit from the automatic
+elastic nature of the embedded etcd servers, and that you're responsible if you
+accidentally break your etcd cluster, or if you use an unsupported version.
+
+### In `mgmt` you talk about events. What is this referring to?
+
+Mgmt has two main concepts that involve "events":
+1. Events in the [resource primitive](resource-guide.md).
+2. Events in the [reactive language](language-guide.md).
+
+Each resource primitive in mgmt can test (check) and set (apply) the desired
+state that was requested of it. This is familiar to what is common with existing
+tools such as `Puppet`, `Ansible`, `Chef`, `Terraform`, etc... In addition,
+`mgmt` can also **watch** the state and detect changes. As a result, it never
+has to waste time and cpu resources by polling to test and set state, leading to
+a design which is algorithmically much faster than the existing generation of
+tools.
+
+To describe the set of resources to apply, mgmt describes this collection with a
+language. In order to model the time component of infrastructure, we use a
+special kind of language called an [FRP](https://en.wikipedia.org/wiki/Functional_reactive_programming).
+This language has a built-in concept that we call "events", and which means that
+we re-evaluate the relevant portions of the code whenever a value or function
+has an event that tells us that it changed. The `R` in `FRP` stands for
+reactive. This is similar to how a spreadsheet updates dependent cells when a
+pre-requisite value is modified. [This article](https://en.wikipedia.org/wiki/Reactive_programming)
+provides a bit more background.
+
+Whenever any of the streams of values in the language change, the program is
+partially re-evaluated. The output of any mgmt program is a [DAG](https://en.wikipedia.org/wiki/Directed_acyclic_graph)
+of resources, or more precisely, a stream of resource graphs. Since we have
+events per-resource, we can efficiently switch from one desired-state resource
+graph to the next without re-checking their individual states, since we've been
+monitoring them all along.
+
+One side-effect of all this, is that if a rogue systems administrator manually
+changes the state of any managed resource, mgmt will detect this and attempt to
+revert the change. This makes for excellent live demos, but is not the primary
+design goal. It is a consequence of tracking state so that graph changes are
+efficient. We implement the event detection via an intentional per-resource
+[main loop](https://en.wikipedia.org/wiki/Event_loop) which can enable other
+interesting functionality too!
+
+Make sure to get rid of your rogue sysadmin! ;)
+
+### Do I need to run `mgmt` as `root`?
+
+No and yes. It depends. Nothing in mgmt explicitly requires root in the design,
+however mgmt will require root only if the changes to your system that you want
+it to make require root.
+
+For example, if you use it to manage files that require root access to modify,
+then you'll need root. If you only use it to manage files and resources
+elsewhere, then it shouldn't need root. Many resources are perfectly usable
+without root, and virtually all of my live demos are done without root.
+
+### How can I run `mgmt` on-demand, or in `cron`, instead of continuously?
+
+By default, `mgmt` will run continuously in an attempt to keep your machine in a
+converged state, even as external forces change the current state, or as your
+time-varying desired state changes over time. (You can write code in the mgmt
+language which will let you describe a desired state which might change over
+time.)
+
+Some users might prefer to only run `mgmt` on-demand manually, or at a set
+interval via a tool like `cron`. In order to do so, `mgmt` must have a way to
+shut itself down after a single "run". This feature is possible with the
+`--converged-timeout` flag. You may specify this flag, along with a number of
+seconds as the argument, and when there has been no activity for that many
+seconds, the program will shutdown.
+
+Alternatively, while it is not recommended, if you'd like to ensure the program
+never runs for longer that a specific number of seconds, you can ask it to
+shutdown after that time interval using the `--max-runtime` flag. This also
+requires a number of seconds as an argument.
+
+#### Example:
+
+```
+./mgmt run lang examples/lang/hello0.mcl --converged-timeout=5
+```
+
+### Can I run `mgmt` for type-checking only?
+
+Yes, you can, add the `--only-unify` option to the lang frontend while using the
+`run` command, and it will exit after type unification.
+
+#### Example:
+
+```
+./mgmt run --tmp-prefix lang --only-unify examples/lang/hello0.mcl
+```
+
+It will also print how long it took on either success or failure. Keep in mind
+that even if you pass type unification, an `mgmt` run can still fail later on
+for other reasons, although these are mostly runtime considerations.
+
+### Why is type unification happening twice with `mgmt run`?
+
+When you use the `run` action, it runs all of the compile time checks (including
+type unification) that are possible, and then packages everything up into a
+deployable object and runs the same mechanism that `mgmt deploy` uses, sending
+the deploy to itself. At this point, mgmt starts up as a server, and receives
+the deploy. It will then need to run type unification again before running the
+code.
+
+You can skip the first type unification check by adding the `--skip-unify`
+option to the lang frontend when using the `run` command.
+
+You can also skip this check when running the `deploy` action, but if your code
+doesn't pass, you might be deploying broken code. This is not recommended.
+
+#### Example:
+
+```
+./mgmt run --tmp-prefix lang --skip-unify examples/lang/hello0.mcl
+```
+
+### Why does my file resource error with `no such file or directory`?
+
+If you create a file resource and only specify the content like this:
+
+```
+file "/tmp/foo" {
+	content => "hello world\n",
+}
+```
+
+Then this will attempt to set the contents of that file to the desired string,
+but *only* if that file already exists. If you'd like to ensure that it also
+gets created in case it is not present, then you must also specify the state:
+
+```
+file "/tmp/foo" {
+	state => $const.res.file.state.exists,
+	content => "hello world\n",
+}
+```
+
+Similar logic applies for situations when you only specify the `mode` parameter.
+
+This all turns out to be more safe and "correct", in that it would error and
+prevent masking an error for a situation when you expected a file to already be
+at that location. It also turns out to simplify the internals significantly, and
+remove an ambiguous scenario with the reversible file resource.
+
+### Why do function names inside of templates include underscores?
+
+The golang template library which we use to implement the template() function
+doesn't support the dot notation, so we import all our normal functions, and
+just replace dots with underscores. As an example, the standard `datetime.print`
+function is shown within mcl scripts as datetime_print after being imported.
+
+### On startup `mgmt` hangs after: `etcd: server: starting...`.
+
+If you get an error message similar to:
+
+```
+etcd: server: starting...
+etcd: server: start timeout of 1m0s reached
+etcd: server: close timeout of 15s reached
+```
+
+But nothing happens afterwards, this can be due to a corrupt etcd storage
+directory. Each etcd server embedded in mgmt must have a special directory where
+it stores local state. It must not be shared by more than one individual member.
+This dir is typically `/var/lib/mgmt/etcd/member/`. If you accidentally use it
+(for example during testing) with a different cluster view, then you can corrupt
+it. This can happen if you use it with more than one different hostname.
+
+The solution is to avoid making this mistake, and if there is no important data
+saved, you can remove the etcd member dir and start over.
+
+### On running `make` to build a new version, it errors with: `Text file busy`.
+
+If you get an error like:
+
+```
+cp: cannot create regular file 'mgmt': Text file busy
+```
+
+This can happen if you ran `make build` (or just `make`) when there was already
+an instance of mgmt running, or if a related file locking issue occurred. To
+solve this, shutdown and running mgmt process, run `rm mgmt` to remove the file,
+and then get a new one by running `make` again.
+
+### Type unification error: "could not unify types: 2 unconsumed generators".
+
+Look carefully at the following code:
+
+```
+$num = 42
+print "hello" {
+	msg => "My favourite number is ${num}",
+}
+```
+
+What's actually happening is that we can't unify `str + int`, because our
+addition operator only supports `str + str`, `int + int`, and `float + float`.
+The string interpolation feature can only combine strings. One solution is to
+instead write:
+
+```
+$num = "42" # now this is a string
+print "hello" {
+	msg => "My favourite number is ${num}",
+}
+```
+
+Yes we know the compiler gives horrible error messages, and yes we would
+absolutely love your help improving this.
+
+### The run and deploy commands don't parse correctly when used with `--seeds`.
+
+If you're running a command with `--seeds`, `--server-urls`, or `--client-urls`,
+then make sure you are using an equals sign between the flag name and the value.
+For example, if you were to run:
+
+```
+# wrong invocation!
+mgmt deploy --no-git --seeds http://127.0.0.1:2379 lang code/test.mcl
+```
+
+Then the `--seeds` flag would interpret `lang` and `code/test.mcl` as additional
+seeds. This flag as well as the other aforementioned ones all accept multiple
+values. Use an equals sign to guarantee you enter the correct data, eg:
+
+```
+# better invocation! (note the equals sign)
+mgmt deploy --no-git --seeds=http://127.0.0.1:2379 lang code/test.mcl
+```
+
+This is caused by a parsing peculiarity of the CLI library that we are using.
+This is tracked upstream at: [https://github.com/alexflint/go-arg/issues/239](https://github.com/alexflint/go-arg/issues/239).
+We have a workaround in place to mitigate it and attempt to show you a helpful
+error message, but it's also documented here in the meantime. The error you will
+see is: `cli parse error: missing equals sign for list element`.
+
+### The docs speaks of `--remote` but the CLI errors out?
+
+The `--remote` flag existed in an earlier version of mgmt. It was removed and
+will be replaced with a more powerful version, which is a "remote" resource. The
+code is mostly ready but it's not finished. If you'd like to help finish it or
+sponsor the work, please let me know.
+
+### Does this support Windows? OSX? GNU Hurd?
+
+Mgmt probably works best on Linux, because that's what most developers use for
+serious automation workloads. Support for non-Linux operating systems isn't a
+high priority of mine, but we're happy to accept patches for missing features
+or resources that you think would make sense on your favourite platform.
+
+### Why aren't you using `glide`, `godep` or `go mod` for dependency management?
+
+Vendoring dependencies means that as the git master branch of each dependency
+marches on, you're left behind using an old version. As a result, bug fixes and
+improvements are not automatically brought into the project. Instead, we run our
+complete test suite against the entire project (with the latest dependencies)
+[every 24 hours](https://docs.travis-ci.com/user/cron-jobs/) to ensure that it
+all still works.
+
+Occasionally a dependency breaks API and causes a failure. In those situations,
+we're notified almost immediately, it's easy to see exactly which commit caused
+the breakage, and we can either quickly notify the author (if it was a mistake)
+or update our code if it was a sensible change. This also puts less burden on
+authors to support old, legacy versions of their software unnecessarily.
+
+Historically, we've had approximately one such breakage per year, which were all
+detected and fixed within a few hours. The cost of these small, rare,
+interruptions is much less expensive than having to periodically move every
+dependency in the project to the latest versions. Some examples of this include:
+
+* We caught the `go-bindata` swap before it was publicly known, and fixed it in:
+[adbe9c7be178898de3645b0ed17ed2ca06646017](https://github.com/purpleidea/mgmt/commit/adbe9c7be178898de3645b0ed17ed2ca06646017).
+
+* We caught the `codegangsta/cli` API change improvement, and fixed it in:
+[ab73261fd4e98cf7ecb08066ad228a8f559ba16a](https://github.com/purpleidea/mgmt/commit/ab73261fd4e98cf7ecb08066ad228a8f559ba16a).
+
+* We caught an un-announced libvirt API change, and promptly fixed it in:
+[95cb94a03958a9d2ebf01df0821a8c13a4f3a28c](https://github.com/purpleidea/mgmt/commit/95cb94a03958a9d2ebf01df0821a8c13a4f3a28c).
+
+If we choose responsible dependencies, then it usually means that those authors
+are also responsible with their changes to API and to git master. If we ever
+find that it's not the case, then we will either switch that dependency to a
+more responsible version, or fork it if necessary.
+
+Occasionally, we want to pin a dependency to a particular version. This can
+happen if the project treats `git master` as an unstable branch, or because a
+dependency needs a newer version of golang than the minimum that we require for
+our project. In those cases it's sensible to assume the technical debt, and
+vendor the dependency. The common tools such as `glide` and `godep` work by
+requiring you install their software, and by either storing a yaml file with the
+version of that dependency in your repository, and/or copying all of that code
+into git and explicitly storing it. This project thinks that all of these
+solutions are wasteful and unnecessary, particularly when an existing elegant
+solution already exists: `[git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)`.
+
+The advantages of using `git submodules` are three-fold:
+1. You already have the required tools installed.
+2. You only store a pointer to the dependency, not additional files or code.
+3. The git submodule tools let you easily switch dependency versions, see diff
+output, and responsibly plan and test your versions bumps with ease.
+
+Don't blindly use the tools that others tell you to. Learn what they do, think
+for yourself, and become a power user today! That process led us to using
+`git submodules`. Hopefully you'll come to the same conclusions that we did.
+
+**UPDATE:**
+
+After golang made it virtually impossible to build without `go.mod` stuff, we've
+switched to it since golang 1.16. I still think the above approach was better,
+and that the `go mod` tooling should have been a layer on top of git submodules
+so that we don't grow yet another lock file format, and existing folks who are
+comfortable with `git` can use those tools directly.
+
+### Did you know that there is a band named `MGMT`?
+
+I didn't realize this when naming the project, and it is accidental. After much
+anguishing, I chose the name because it was short and I thought it was
+appropriately descriptive. If you need a less ambiguous search term or phrase,
+you can try using `mgmtconfig` or `mgmt config`.
+
+It also doesn't stand for
+[Methyl Guanine Methyl Transferase](https://en.wikipedia.org/wiki/O-6-methylguanine-DNA_methyltransferase)
+which definitely existed before the band did.
+
+### You didn't answer my question, or I have a question!
+
+It's best to ask on [IRC](https://web.libera.chat/?channels=#mgmtconfig)
+to see if someone can help you. If you don't get a response from IRC, you can
+contact me through my [technical blog](https://purpleidea.com/contact/) and I'll
+do my best to help. If you have a good question, please add it as a patch to
+this documentation. I'll merge your question, and add a patch with the answer!
+For news and updates, subscribe to the [mailing list](https://www.redhat.com/mailman/listinfo/mgmtconfig-list).

docs/function-guide.md

@@ -0,0 +1,441 @@
+# Function guide
+
+## Overview
+
+The `mgmt` tool has built-in functions which add useful, reactive functionality
+to the language. This guide describes the different function API's that are
+available. It is meant to instruct developers on how to write new functions.
+Since `mgmt` and the core functions are written in golang, some prior golang
+knowledge is assumed.
+
+## Theory
+
+Functions in `mgmt` are similar to functions in other languages, however they
+also have a [reactive](https://en.wikipedia.org/wiki/Functional_reactive_programming)
+component. Our functions can produce events over time, and there are different
+ways to write functions. For some background on this design, please read the
+[original article](https://purpleidea.com/blog/2018/02/05/mgmt-configuration-language/)
+on the subject.
+
+## Native Functions
+
+Native functions are functions which are implemented in the mgmt language
+itself. These are currently not available yet, but are coming soon. Stay tuned!
+
+## Simple Function API
+
+Most functions should be implemented using the simple function API. This API
+allows you to implement simple, static, [pure](https://en.wikipedia.org/wiki/Pure_function)
+functions that don't require you to write much boilerplate code. They will be
+automatically re-evaluated as needed when their input values change. These will
+all be automatically made available as helper functions within mgmt templates,
+and are also available for use anywhere inside mgmt programs.
+
+You'll need some basic knowledge of using the [`types`](https://github.com/purpleidea/mgmt/tree/master/lang/types)
+library which is included with mgmt. This library lets you interact with the
+available types and values in the mgmt language. It is very easy to use, and
+should be fairly intuitive. Most of what you'll need to know can be inferred
+from looking at example code.
+
+To implement a function, you'll need to create a file that imports the
+[`lang/funcs/simple/`](https://github.com/purpleidea/mgmt/tree/master/lang/funcs/simple/)
+module. It should probably get created in the correct directory inside of:
+[`lang/core/`](https://github.com/purpleidea/mgmt/tree/master/lang/core/). The
+function should be implemented as a `FuncValue` in our type system. It is then
+registered with the engine during `init()`. An example explains it best:
+
+### Example
+
+```golang
+package simple
+
+import (
+	"fmt"
+
+	"github.com/purpleidea/mgmt/lang/funcs/simple"
+	"github.com/purpleidea/mgmt/lang/types"
+)
+
+// you must register your functions in init when the program starts up
+func init() {
+	// Example function that squares an int and prints out answer as an str.
+	simple.ModuleRegister(ModuleName, "talkingsquare", &types.FuncValue{
+		T: types.NewType("func(int) str"), // declare the signature
+		V: func(input []types.Value) (types.Value, error) {
+			i := input[0].Int() // get first arg as an int64
+			// must return the above specified value
+			return &types.StrValue{
+				V: fmt.Sprintf("%d^2 is %d", i, i * i),
+			}, nil // no serious errors occurred
+		},
+	})
+}
+```
+
+This simple function accepts one `int` as input, and returns one `str`.
+Functions can have zero or more inputs, and must have exactly one output. You
+must be sure to use the `types` library correctly, since if you try and access
+an input which should not exist (eg: `input[2]`, when there are only two
+that are expected), then you will cause a panic. If you have declared that a
+particular argument is an `int` but you try to read it with `.Bool()` you will
+also cause a panic. Lastly, make sure that you return a value in the correct
+type or you will also cause a panic!
+
+If anything goes wrong, you can return an error, however this will cause the
+mgmt engine to shutdown. It should be seen as the equivalent to calling a
+`panic()`, however it is safer because it brings the engine down cleanly.
+Ideally, your functions should never need to error. You should never cause a
+real `panic()`, since this could have negative consequences to the system.
+
+## Simple Polymorphic Function API
+
+Most functions should be implemented using the simple function API. If they need
+to have multiple polymorphic forms under the same name, then you can use this
+API. This is useful for situations when it would be unhelpful to name the
+functions differently, or when the number of possible signatures for the
+function would be infinite.
+
+The canonical example of this is the `len` function which returns the number of
+elements in either a `list` or a `map`. Since lists and maps are two different
+types, you can see that polymorphism is more convenient than requiring a
+`listlen` and `maplen` function. Nevertheless, it is also required because a
+`list of int` is a different type than a `list of str`, which is a different
+type than a `list of list of str` and so on. As you can see the number of
+possible input types for such a `len` function is infinite.
+
+Another downside to implementing your functions with this API is that they will
+*not* be made available for use inside templates. This is a limitation of the
+`golang` template library. In the future if this limitation proves to be
+significantly annoying, we might consider writing our own template library.
+
+As with the simple, non-polymorphic API, you can only implement [pure](https://en.wikipedia.org/wiki/Pure_function)
+functions, without writing too much boilerplate code. They will be automatically
+re-evaluated as needed when their input values change.
+
+To implement a function, you'll need to create a file that imports the
+[`lang/funcs/simplepoly/`](https://github.com/purpleidea/mgmt/tree/master/lang/funcs/simplepoly/)
+module. It should probably get created in the correct directory inside of:
+[`lang/core/`](https://github.com/purpleidea/mgmt/tree/master/lang/core/). The
+function should be implemented as a list of `FuncValue`'s in our type system. It
+is then registered with the engine during `init()`. You may also use the
+`variant` type in your type definitions. This special type will never be seen
+inside a running program, and will get converted to a concrete type if a
+suitable match to this signature can be found. Be warned that signatures which
+contain too many variants, or which are very general, might be hard for the
+compiler to match, and ambiguous type graphs make for user compiler errors. The
+top-level type must still be a function type, it may only contain variants as
+part of its signature. It is probably more difficult to unify a function if its
+return type is a variant, as opposed to if one of its args was.
+
+An example explains it best:
+
+### Example
+
+```golang
+import (
+	"fmt"
+
+	"github.com/purpleidea/mgmt/lang/funcs/simplepoly"
+	"github.com/purpleidea/mgmt/lang/types"
+)
+
+func init() {
+	// You may use the simplepoly.ModuleRegister method to register your
+	// function if it's in a module, as seen in the simple function example.
+	simplepoly.Register("len", []*types.FuncValue{
+		{
+			T: types.NewType("func([]variant) int"),
+			V: Len,
+		},
+		{
+			T: types.NewType("func({variant: variant}) int"),
+			V: Len,
+		},
+	})
+}
+
+// Len returns the number of elements in a list or the number of key pairs in a
+// map. It can operate on either of these types.
+func Len(input []types.Value) (types.Value, error) {
+	var length int
+	switch k := input[0].Type().Kind; k {
+	case types.KindList:
+		length = len(input[0].List())
+	case types.KindMap:
+		length = len(input[0].Map())
+
+	default:
+		return nil, fmt.Errorf("unsupported kind: %+v", k)
+	}
+
+	return &types.IntValue{
+		V: int64(length),
+	}, nil
+}
+```
+
+This simple polymorphic function can accept an infinite number of signatures, of
+which there are two basic forms. Both forms return an `int` as is seen above.
+The first form takes a `[]variant` which means a `list` of `variant`'s, which
+means that it can be a list of any type, since `variant` itself is not a
+concrete type. The second form accepts a `{variant: variant}`, which means that
+it accepts any form of `map` as input.
+
+The implementation for both of these forms is the same: it is handled by the
+same `Len` function which is clever enough to be able to deal with any of the
+type signatures possible from those two patterns.
+
+At compile time, if your `mcl` code type checks correctly, a concrete type will
+be known for each and every usage of the `len` function, and specific values
+will be passed in for this code to compute the length of. As usual, make sure to
+only write safe code that will not panic! A panic is a bug. If you really cannot
+continue, then you must return an error.
+
+## Function API
+
+To implement a reactive function in `mgmt` it must satisfy the
+[`Func`](https://github.com/purpleidea/mgmt/blob/master/lang/interfaces/func.go)
+interface. Using the [Simple Function API](#simple-function-api) is preferable
+if it meets your needs. Most functions will be able to use that API. If you
+really need something more powerful, then you can use the regular function API.
+What follows are each of the method signatures and a description of each.
+
+### Info
+
+```golang
+Info() *interfaces.Info
+```
+
+This returns some information about the function. It is necessary so that the
+compiler can type check the code correctly, and know what optimizations can be
+performed. This is usually the first method which is called by the engine.
+
+#### Example
+
+```golang
+func (obj *FooFunc) Info() *interfaces.Info {
+	return &interfaces.Info{
+		Pure: true,
+		Sig:  types.NewType("func(a int) str"),
+	}
+}
+```
+
+### Init
+
+```golang
+Init(init *interfaces.Init) error
+```
+
+This is called to initialize the function. If something goes wrong, it should
+return an error. It is passed a struct that contains all the important
+information and pointers that it might need to work with throughout its
+lifetime. As a result, it will need to save a copy to that pointer for future
+use in the other methods.
+
+#### Example
+
+```golang
+// Init runs some startup code for this function.
+func (obj *FooFunc) Init(init *interfaces.Init) error {
+	obj.init = init
+	return nil
+}
+```
+
+### Stream
+
+```golang
+Stream(context.Context) error
+```
+
+`Stream` is where the real _work_ is done. This method is started by the
+language function engine. It will run this function while simultaneously sending
+it values on the `Input` channel. It will only send a complete set of input
+values. You should send a value to the output channel when you have decided that
+one should be produced. Make sure to only use input values of the expected type
+as declared in the `Info` struct, and send values of the similarly declared
+appropriate return type. Failure to do so will may result in a panic and
+sadness. You must shutdown if the input context cancels. You must close the
+`Output` channel if you are done generating new values and/or when you shutdown.
+
+#### Example
+
+```golang
+// Stream returns the single value that was generated and then closes.
+func (obj *FooFunc) Stream(ctx context.Context) error {
+	defer close(obj.init.Output) // the sender closes
+	var result string
+	for {
+		select {
+		case input, ok := <-obj.init.Input:
+			if !ok {
+				return nil // can't output any more
+			}
+
+			ix := input.Struct()["a"].Int()
+			if ix < 0 {
+				return fmt.Errorf("we can't deal with negatives")
+			}
+
+			result = fmt.Sprintf("the input is: %d", ix)
+
+		case <-ctx.Done():
+			return nil
+		}
+
+		select {
+		case obj.init.Output <- &types.StrValue{
+			V: result,
+		}:
+
+		case <-ctx.Done():
+			return nil
+		}
+	}
+}
+```
+
+As you can see, we read our inputs from the `input` channel, and write to the
+`output` channel. Our code is careful to never block or deadlock, and can always
+exit if a close signal is requested. It also cleans up after itself by closing
+the `output` channel when it is done using it. This is done easily with `defer`.
+If it notices that the `input` channel closes, then it knows that no more input
+values are coming and it can consider shutting down early.
+
+## Further considerations
+
+There is some additional information that any function author will need to know.
+Each issue is listed separately below!
+
+### Function struct
+
+Each function will implement methods as pointer receivers on a function struct.
+The naming convention for resources is that they end with a `Func` suffix.
+
+#### Example
+
+```golang
+type FooFunc struct {
+	init *interfaces.Init
+
+	// this space can be used if needed
+}
+```
+
+### Function registration
+
+All functions must be registered with the engine so that they can be found. This
+also ensures they can be encoded and decoded. Make sure to include the following
+code snippet for this to work.
+
+```golang
+import "github.com/purpleidea/mgmt/lang/funcs"
+
+func init() { // special golang method that runs once
+	funcs.Register("foo", func() interfaces.Func { return &FooFunc{} })
+}
+```
+
+Functions inside of built-in modules will need to use the `ModuleRegister`
+method instead.
+
+```golang
+// moduleName is already set to "math" by the math package. Do this in `init`.
+funcs.ModuleRegister(moduleName, "cos", func() interfaces.Func {
+	return &CosFunc{}
+})
+```
+
+### Composite functions
+
+Composite functions are functions which import one or more existing functions.
+This is useful to prevent code duplication in higher level function scenarios.
+Unfortunately no further documentation about this subject has been written. To
+expand this section, please send a patch! Please contact us if you'd like to
+work on a function that uses this feature, or to add it to an existing one!
+We don't expect this functionality to be particularly useful or common, as it's
+probably easier and preferable to simply import common golang library code into
+multiple different functions instead.
+
+## Polymorphic Function API
+
+The polymorphic function API is an API that lets you implement functions which
+do not necessarily have a single static function signature. After compile time,
+all functions must have a static function signature. We also know that there
+might be different ways you would want to call `printf`, such as:
+`printf("the %s is %d", "answer", 42)` or `printf("3 * 2 = %d", 3 * 2)`. Since
+you couldn't implement the infinite number of possible signatures, this API lets
+you write code which can be coerced into different forms. This makes
+implementing what would appear to be generic or polymorphic, instead of
+something that is actually static and that still has the static type safety
+properties that were guaranteed by the mgmt language.
+
+Since this is an advanced topic, it is not described in full at this time. For
+more information please have a look at the source code comments, some of the
+existing implementations, and ask around in the community.
+
+## Frequently asked questions
+
+(Send your questions as a patch to this FAQ! I'll review it, merge it, and
+respond by commit with the answer.)
+
+### Can I use global variables?
+
+Probably not. You must assume that multiple copies of your function may be used
+at the same time. If they require a global variable, it's likely this won't
+work. Instead it's probably better to use a struct local variable if you need to
+store some state.
+
+There might be some rare instances where a global would be acceptable, but if
+you need one of these, you're probably already an internals expert. If you think
+they need to lock or synchronize so as to not overwhelm an external resource,
+then you have to be especially careful not to cause deadlocking the mgmt engine.
+
+### Can I write functions in a different language?
+
+Currently `golang` is the only supported language for built-in functions. We
+might consider allowing external functions to be imported in the future. This
+will likely require a language that can expose a C-like API, such as `python` or
+`ruby`. Custom `golang` functions are already possible when using mgmt as a lib.
+
+### What new functions need writing?
+
+There are still many ideas for new functions that haven't been written yet. If
+you'd like to contribute one, please contact us and tell us about your idea!
+
+### Can I generate many different `FuncValue` implementations from one function?
+
+Yes, you can use a function generator in `golang` to build multiple different
+implementations from the same function generator. You just need to implement a
+function which *returns* a `golang` type of `func([]types.Value) (types.Value, error)`
+which is what `FuncValue` expects. The generator function can use any input it
+wants to build the individual functions, thus helping with code re-use.
+
+### How do I determine the signature of my simple, polymorphic function?
+
+The determination of the input portion of the function signature can be
+determined by inspecting the length of the input, and the specific type each
+value has. Length is done in the standard `golang` way, and the type of each
+element can be ascertained with the `Type()` method available on every value.
+
+Knowing the output type is trickier. If it can not be inferred in some manner,
+then the only way is to keep track of this yourself. You can use a function
+generator to build your `FuncValue` implementations, and pass in the unique
+signature to each one as you are building them. Using a generator is a common
+technique which was mentioned previously.
+
+One obvious situation where this might occur is if your function doesn't take
+any inputs! An example `math.fortytwo()` function was implemented that
+demonstrates the use of function generators to pass the type signatures into the
+implementations.
+
+### Where can I find more information about mgmt?
+
+Additional blog posts, videos and other material [is available!](https://github.com/purpleidea/mgmt/blob/master/docs/on-the-web.md).
+
+## Suggestions
+
+If you have any ideas for API changes or other improvements to function writing,
+please let us know! We're still pre 1.0 and pre 0.1 and happy to break API in
+order to get it right!

docs/index.rst

@@ -0,0 +1,16 @@
+.. mgmt documentation master file, created by
+   sphinx-quickstart on Wed Feb 15 21:34:09 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to mgmt's documentation!
+================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   documentation
+   quick-start-guide
+   resource-guide
+   prometheus

docs/language-guide.md

@@ -0,0 +1,984 @@
+# Language guide
+
+## Overview
+
+The `mgmt` tool has various frontends, each of which may produce a stream of
+between zero or more graphs that are passed to the engine for desired state
+application. In almost all scenarios, you're going to want to use the language
+frontend. This guide describes some of the internals of the language.
+
+## Theory
+
+The mgmt language is a declarative (immutable) functional, reactive programming
+language. It is implemented in `golang`. A longer introduction to the language
+is [available as a blog post here](https://purpleidea.com/blog/2018/02/05/mgmt-configuration-language/)!
+
+### Types
+
+All expressions must have a type. A composite type such as a list of strings
+(`[]str`) is different from a list of integers (`[]int`).
+
+There _is_ a _variant_ type in the language's type system, but it is only used
+internally and only appears briefly when needed for type unification hints
+during static polymorphic function generation. This is an advanced topic which
+is not required for normal usage of the software.
+
+The implementation of the internal types can be found in
+[lang/types/](https://github.com/purpleidea/mgmt/tree/master/lang/types/).
+
+#### bool
+
+A `true` or `false` value.
+
+#### str
+
+Any `"string!"` enclosed in quotes.
+
+#### int
+
+A number like `42` or `-13`. Integers are represented internally as golang's
+`int64`.
+
+#### float
+
+A floating point number like: `3.1415926`. Float's are represented internally as
+golang's `float64`.
+
+#### list
+
+An ordered collection of values of the same type, eg: `[6, 7, 8, 9,]`. It is
+worth mentioning that empty lists have a type, although without type hints it
+can be impossible to infer the item's type.
+
+#### map
+
+An unordered set of unique keys of the same type and corresponding value pairs
+of another type, eg:
+`{"boiling" => 100, "freezing" => 0, "room" => 25, "house" => 22, "canada" => -30,}`.
+That is to say, all of the keys must have the same type, and all of the values
+must have the same type. You can use any type for either, although it is
+probably advisable to avoid using very complex types as map keys.
+
+#### struct
+
+An ordered set of field names and corresponding values, each of their own type,
+eg: `struct{answer => "42", james => "awesome", is_mgmt_awesome => true,}`.
+These are useful for combining more than one type into the same value. Note the
+syntactical difference between these and map's: the key's in map's have types,
+and as a result, string keys are enclosed in quotes, whereas struct _fields_ are
+not string values, and as such are bare and specified without quotes.
+
+#### func
+
+An ordered set of optionally named, differently typed input arguments, and a
+return type, eg: `func(s str) int` or:
+`func(bool, []str, {str: float}) struct{foo str; bar int}`.
+
+### Expressions
+
+Expressions, and the `Expr` interface need to be better documented. For now
+please consume
+[lang/interfaces/ast.go](https://github.com/purpleidea/mgmt/tree/master/lang/interfaces/ast.go).
+These docs will be expanded on when things are more certain to be stable.
+
+### Statements
+
+There are a very small number of statements in our language. They include:
+
+- **bind**: bind's an expression to a variable within that scope without output
+	- eg: `$x = 42`
+
+- **if**: produces up to one branch of statements based on a conditional
+expression
+
+	```mcl
+	if <conditional> {
+		<statements>
+	} else {
+		# the else branch is optional for if statements
+		<statements>
+	}
+	```
+
+- **resource**: produces a resource
+
+	```mcl
+	file "/tmp/hello" {
+		content => "world",
+		mode => "o=rwx",
+	}
+	```
+
+- **edge**: produces an edge
+
+	```mcl
+	File["/tmp/hello"] -> Print["alert4"]
+	```
+
+- **class**: bind's a list of statements to a class name in scope without output
+
+	```mcl
+	class foo {
+		# some statements go here
+	}
+	```
+
+	or
+
+	```mcl
+	class bar($a, $b) { # a parameterized class
+		# some statements go here
+	}
+	```
+
+- **include**: include a particular class at this location producing output
+
+	```mcl
+	include foo
+
+	include bar("hello", 42)
+	include bar("world", 13) # an include can be called multiple times
+	```
+
+- **import**: import a particular scope from this location at a given namespace
+
+	```mcl
+	# a system module import
+	import "fmt"
+
+	# a local, single file import (relative path, not a module)
+	import "dir1/file.mcl"
+
+	# a local, module import (relative path, contents are a module)
+	import "dir2/"
+
+	# a remote module import (absolute remote path, contents are a module)
+	import "git://github.com/purpleidea/mgmt-example1/"
+	```
+
+	or
+
+	```mcl
+	import "fmt" as *	# contents namespaced into top-level names
+	import "foo.mcl"	# namespaced as foo
+	import "dir1/" as bar	# namespaced as bar
+	import "git://github.com/purpleidea/mgmt-example1/"	# namespaced as example1
+	```
+
+All statements produce _output_. Output consists of between zero and more
+`edges` and `resources`. A resource statement can produce a resource, whereas an
+`if` statement produces whatever the chosen branch produces. Ultimately the goal
+of executing our programs is to produce a list of `resources`, which along with
+the produced `edges`, is built into a resource graph. This graph is then passed
+to the engine for desired state application.
+
+#### Bind
+
+This section needs better documentation.
+
+#### If
+
+This section needs better documentation.
+
+#### Resource
+
+Resources express the idempotent workloads that we want to have apply on our
+system. They correspond to vertices in a [graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph)
+which represent the order in which their declared state is applied. You will
+usually want to pass in a number of parameters and associated values to the
+resource to control how it behaves. For example, setting the `content` parameter
+of a `file` resource to the string `hello`, will cause the contents of that file
+to contain the string `hello` after it has run.
+
+##### Undefined parameters
+
+For some parameters, there is a distinction between an unspecified parameter,
+and a parameter with a `zero` value. For example, for the file resource, you
+might choose to set the `content` parameter to be the empty string, which would
+ensure that the file has a length of zero. Alternatively you might wish to not
+specify the file contents at all, which would leave that property undefined. If
+you omit listing a property, then it will be undefined. To control this property
+programmatically, you need to specify an `is-defined` value, as well as the
+value to use if that boolean is true. You can do this with the resource-specific
+`elvis` operator.
+
+```mcl
+$b = true # change me to false and then try editing the file manually
+file "/tmp/mgmt-elvis" {
+	content => $b ?: "hello world\n",
+	state => $const.res.file.state.exists,
+}
+```
+
+This example is static, however you can imagine that the `$b` value might be
+chosen in a programmatic way, even one in which that value varies over time. If
+it evaluates to `true`, then the parameter will be used. If no `elvis` operator
+is specified, then the parameter value will also be used. If the parameter is
+not specified, then it will obviously not be used.
+
+##### Meta parameters
+
+Resources may specify meta parameters. To do so, you must add them as you would
+a regular parameter, except that they start with `Meta` and are capitalized. Eg:
+
+```mcl
+file "/tmp/f1" {
+	content => "hello!\n",
+
+	Meta:noop => true,
+	Meta:delay => $b ?: 42,
+	Meta:autoedge => false,
+}
+```
+
+As you can see, they also support the elvis operator, and you can add as many as
+you like. While it is not recommended to add the same meta parameter more than
+once, it does not currently cause an error, and even though the result of doing
+so is officially undefined, it will currently take the last specified value.
+
+You may also specify a single meta parameter struct. This is useful if you'd
+like to reuse a value, or build a combined value programmatically. For example:
+
+```mcl
+file "/tmp/f1" {
+	content => "hello!\n",
+
+	Meta => $b ?: struct{
+		noop => false,
+		retry => -1,
+		delay => 0,
+		poll => 5,
+		limit => 4.2,
+		burst => 3,
+		sema => ["foo:1", "bar:3",],
+		autoedge => true,
+		autogroup => false,
+	},
+}
+```
+
+Remember that the top-level `Meta` field supports the elvis operator, while the
+individual struct fields in the struct type do not. This is to be expected, but
+since they are syntactically similar, it is worth mentioning to avoid confusion.
+
+Please note that at the moment, you must specify a full metaparams struct, since
+partial struct types are currently not supported in the language. Patches are
+welcome if you'd like to add this tricky feature!
+
+##### Resource naming
+
+Each resource must have a unique name of type `str` that is used to uniquely
+identify that resource, and can be used in the functioning of the resource at
+that resources discretion. For example, the `file` resource uses the unique name
+value to specify the path.
+
+Alternatively, the name value may be a list of strings `[]str` to build a list
+of resources, each with a name from that list. When this is done, each resource
+will use the same set of parameters. The list of internal edges specified in the
+same resource block is created intelligently to have the appropriate edge for
+each separate resource.
+
+Using this construct is a veiled form of looping (iteration). This technique is
+one of many ways you can perform iterative tasks that you might have
+traditionally used a `for` loop for instead. This is preferred, because flow
+control is error-prone and can make for less readable code.
+
+##### Internal edges
+
+Resources may also declare edges internally. The edges may point to or from
+another resource, and may optionally include a notification. The four properties
+are: `Before`, `Depend`, `Notify` and `Listen`. The first two represent normal
+edge dependencies, and the second two are normal edge dependencies that also
+send notifications. You may have multiples of these per resource, including
+multiple `Depend` lines if necessary. Each of these properties also supports the
+conditional inclusion `elvis` operator as well.
+
+For example, you may write:
+
+```mcl
+$b = true # for example purposes
+if $b {
+	pkg "drbd" {
+		state => "installed",
+
+		# multiple properties may be used in the same resource
+		Before => File["/etc/drbd.conf"],
+		Before => Svc["drbd"],
+	}
+}
+file "/etc/drbd.conf" {
+	content => "some config",
+
+	Depend => $b ?: Pkg["drbd"],
+	Notify => Svc["drbd"],
+}
+svc "drbd" {
+	state => "running",
+}
+```
+
+There are two unique properties about these edges that is different from what
+you might expect from other automation software:
+
+1. The ability to specify multiples of these properties allows you to avoid
+having to manage arrays and conditional trees of these different dependencies.
+2. The keywords all have the same length, which means your code lines up nicely.
+
+#### Edge
+
+Edges express dependencies in the graph of resources which are output. They can
+be chained as a pair, or in any greater number. For example, you may write:
+
+```mcl
+Pkg["drbd"] -> File["/etc/drbd.conf"] -> Svc["drbd"]
+```
+
+to express a relationship between three resources. The first character in the
+resource kind must be capitalized so that the parser can't ascertain
+unambiguously that we are referring to a dependency relationship.
+
+#### Class
+
+A class is a grouping structure that bind's a list of statements to a name in
+the scope where it is defined. It doesn't directly produce any output. To
+produce output it must be called via the `include` statement.
+
+Defining classes follows the same scoping and shadowing rules that is applied to
+the `bind` statement, although they exist in a separate namespace. In other
+words you can have a variable named `foo` and a class named `foo` in the same
+scope without any conflicts.
+
+Classes can be both parameterized or naked. If a parameterized class is defined,
+then the argument types must be either specified manually, or inferred with the
+type unification algorithm. One interesting property is that the same class
+definition can be used with `include` via two different input signatures,
+although in practice this is probably fairly rare. Some usage examples include:
+
+A naked class definition:
+
+```mcl
+class foo {
+	# some statements go here
+}
+```
+
+A parameterized class with both input types being inferred if possible:
+
+```mcl
+class bar($a, $b) {
+	# some statements go here
+}
+```
+
+A parameterized class with one type specified statically and one being inferred:
+
+```mcl
+class baz($a str, $b) {
+	# some statements go here
+}
+```
+
+Classes can also be nested within other classes. Here's a contrived example:
+
+```mcl
+import "fmt"
+class c1($a, $b) {
+	# nested class definition
+	class c2($c) {
+		test $a {
+			stringptr => fmt.printf("%s is %d", $b, $c),
+		}
+	}
+
+	if $a == "t1" {
+		include c2(42)
+	}
+}
+```
+
+Defining polymorphic classes was considered but is not currently allowed at this
+time.
+
+Recursive classes are not currently supported and it is not clear if they will
+be in the future. Discussion about this topic is welcome on the mailing list.
+
+A class names can contain colons to indicate it is nested inside of the class in
+the same scope which is named with the prefix indicated by colon separation.
+Instead of needing to repeatedly indent the child classes, we can instead prefix
+them at the definition site (where created with the class keyword) with the name
+of the parent class, followed by a colon, to get the desired embedded sugar.
+
+For example, instead of writing:
+
+```mcl
+class base() {
+	class inner() {
+		class deepest() {
+		}
+	}
+}
+```
+
+You can instead write:
+
+```mcl
+class base() {
+}
+class base:inner() {
+}
+class base:inner:deepest() {
+}
+```
+
+Of course, you can only access any of the inner classes by first including
+(with the include keyword) a parent class, and then subsequently including the
+inner one.
+
+#### Include
+
+The `include` statement causes the previously defined class to produce the
+contained output. This statement must be called with parameters if the named
+class is defined with those.
+
+The defined class can be called as many times as you'd like either within the
+same scope or within different scopes. If a class uses inferred type input
+parameters, then the same class can even be called with different signatures.
+Whether the output is useful and whether there is a unique type unification
+solution is dependent on your code.
+
+Classes can be included under a new scoped prefix by using the `as` field and an
+identifier. When used in this manner, the captured scope of the class at its
+definition site are made available in the scope of the include. Variables,
+functions, and child classes are all exported.
+
+Variables are available in the include scope:
+
+```mcl
+import "fmt"
+
+class c1 {
+	test "t1" {}	# gets pulled out
+	$x = "hello"	# gets exported
+}
+include c1 as i1
+
+test "print0" {
+	anotherstr => fmt.printf("%s", $i1.x),	# hello
+	onlyshow => ["AnotherStr",], # displays nicer
+}
+```
+
+Classes are also available in the new scope:
+
+```mcl
+import "fmt"
+class c1 {
+	test "t1" {}	# gets pulled out
+	$x = "hello"	# gets exported
+
+	class c0 {
+		test "t2" {}
+		$x = "goodbye"
+	}
+}
+include c1 as i1
+include i1.c0 as i0
+
+test "print0" {
+	anotherstr => fmt.printf("%s", $i1.x),	# hello
+	onlyshow => ["AnotherStr",], # displays nicer
+}
+test "print1" {
+	anotherstr => fmt.printf("%s", $i0.x),	# goodbye
+	onlyshow => ["AnotherStr",], # displays nicer
+}
+```
+
+Of course classes can be parameterized too, and those variables specified during
+the `include`.
+
+#### Import
+
+The `import` statement imports a scope into the specified namespace. A scope can
+contain variable, class, and function definitions. All are statements.
+Furthermore, since each of these have different logical uses, you could
+theoretically import a scope that contains an `int` variable named `foo`, a
+class named `foo`, and a function named `foo` as well. Keep in mind that
+variables can contain functions (they can have a type of function) and are
+commonly called lambdas.
+
+There are a few different kinds of imports. They differ by the string contents
+that you specify. Short single word, or multiple-word tokens separated by zero
+or more slashes are system imports. Eg: `math`, `fmt`, or even `math/trig`.
+Local imports are path imports that are relative to the current directory. They
+can either import a single `mcl` file, or an entire well-formed module. Eg:
+`file1.mcl` or `dir1/`. Lastly, you can have a remote import. This must be an
+absolute path to a well-formed module. The common transport is `git`, and it can
+be represented via an FQDN. Eg: `git://github.com/purpleidea/mgmt-example1/`.
+
+The namespace that any of these are imported into depends on how you use the
+import statement. By default, each kind of import will have a logic namespace
+identifier associated with it. System imports use the last token in their name.
+Eg: `fmt` would be imported as `fmt` and `math/trig` would be imported as
+`trig`. Local imports do the same, except the required `.mcl` extension, or
+trailing slash are removed. Eg: `foo/file1.mcl` would be imported as `file1` and
+`bar/baz/` would be imported as `baz`. Remote imports use some more complex
+rules. In general, well-named modules that contain a final directory name in the
+form: `mgmt-whatever/` will be named `whatever`. Otherwise, the last path token
+will be converted to lowercase and the dashes will be converted to underscores.
+The rules for remote imports might change, and should not be considered stable.
+
+In any of the import cases, you can change the namespace that you're imported
+into. Simply add the `as whatever` text at the end of the import, and `whatever`
+will be the name of the namespace. Please note that `whatever` is not surrounded
+by quotes, since it is an identifier, and not a `string`. If you'd like to add
+all of the import contents into the top-level scope, you can use the `as *` text
+to dump all of the contents in. This is generally not recommended, as it might
+cause a conflict with another identifier.
+
+### Stages
+
+The mgmt compiler runs in a number of stages. In order of execution they are:
+* [Lexing](#lexing)
+* [Parsing](#parsing)
+* [Interpolation](#interpolation)
+* [Scope propagation](#scope-propagation)
+* [Type unification](#type-unification)
+* [Function graph generation](#function-graph-generation)
+* [Function engine creation and validation](#function-engine-creation-and-validation)
+
+All of the above needs to be done every time the source code changes. After this
+point, the [function engine runs](#function-engine-running-and-interpret) and
+produces events. On every event, we "[interpret](#function-engine-running-and-interpret)"
+which produces a resource graph. This series of resource graphs are passed
+to the engine as they are produced.
+
+What follows are some notes about each step.
+
+#### Lexing
+
+Lexing is done using [nex](https://github.com/blynn/nex). It is a pure-golang
+implementation which is similar to _Lex_ or _Flex_, but which produces golang
+code instead of C. It integrates reasonably well with golang's _yacc_ which is
+used for parsing. The token definitions are in:
+[lang/lexer.nex](https://github.com/purpleidea/mgmt/tree/master/lang/lexer.nex).
+Lexing and parsing run together by calling the `LexParse` method.
+
+#### Parsing
+
+The parser used is golang's implementation of
+[yacc](https://godoc.org/golang.org/x/tools/cmd/goyacc). The documentation is
+quite abysmal, so it's helpful to rely on the documentation from standard yacc
+and trial and error. One small advantage yacc has over standard yacc is that it
+can produce error messages from examples. The best documentation is to examine
+the source. There is a short write up available [here](https://research.swtch.com/yyerror).
+The yacc file exists at:
+[lang/parser.y](https://github.com/purpleidea/mgmt/tree/master/lang/parser.y).
+Lexing and parsing run together by calling the `LexParse` method.
+
+#### Interpolation
+
+Interpolation is used to transform the AST (which was produced from lexing and
+parsing) into one which is either identical or different. It expands strings
+which might contain expressions to be interpolated (eg: `"the answer is: ${foo}"`)
+and can be used for other scenarios in which one statement or expression would
+be better represented by a larger AST. Most nodes in the AST simply return their
+own node address, and do not modify the AST.
+
+This stage also implements the class nesting when it finds class names with
+colons that should be nested inside of a base class. Currently this does modify
+the AST for efficiency and simplicity.
+
+#### Scope propagation
+
+Scope propagation passes the parent scope (starting with the top-level, built-in
+scope) down through the AST. This is necessary so that children nodes can access
+variables in the scope if needed. Most AST node's simply pass on the scope
+without making any changes. The `ExprVar` node naturally consumes scope's and
+the `StmtProg` node cleverly passes the scope through in the order expected for
+the out-of-order bind logic to work.
+
+This step typically calls the ordering algorithm to determine the correct order
+of statements in a program.
+
+#### Type unification
+
+Each expression must have a known type. The unpleasant option is to force the
+programmer to specify by annotation every type throughout their whole program
+so that each `Expr` node in the AST knows what to expect. Type annotation is
+allowed in situations when you want to explicitly specify a type, or when the
+compiler cannot deduce it, however, most of it can usually be inferred.
+
+For type inferrence to work, each node in the AST implements a `Unify` method
+which is able to return a list of invariants that must hold true. This starts at
+the top most AST node, and gets called through to it's children to assemble a
+giant list of invariants. The invariants can take different forms. They can
+specify that a particular expression must have a particular type, or they can
+specify that two expressions must have the same types. More complex invariants
+allow you to specify relationships between different types and expressions.
+Furthermore, invariants can allow you to specify that only one invariant out of
+a set must hold true.
+
+Once the list of invariants has been collected, they are run through an
+invariant solver. The solver can return either return successfully or with an
+error. If the solver returns successfully, it means that it has found a trivial
+mapping between every expression and it's corresponding type. At this point it
+is a simple task to run `SetType` on every expression so that the types are
+known. If the solver returns in error, it is usually due to one of two
+possibilities:
+
+1. Ambiguity
+
+	The solver does not have enough information to make a definitive or
+	unique determination about the expression to type mappings. The set of
+	invariants is ambiguous, and we cannot continue. An error will be
+	returned to the programmer. In this scenario the user will probably need
+	to add a type annotation, possibly because of a design bug in the user's
+	program.
+
+2. Conflict
+
+	The solver has conflicting information that cannot be reconciled. In
+	this situation an explicit conflict has been found. If two invariants
+	are found which both expect a particular expression to have different
+	types, then it is not possible to find a valid solution. This almost
+	always happens if the user has made a type error in their program.
+
+Only one solver currently exists, but it is possible to easily plug in an
+alternate implementation if someone more skilled in the art of solver design
+would like to propose a more logical or performant variant.
+
+#### Function graph generation
+
+At this point we have a fully typed AST. The AST must now be transformed into a
+directed, acyclic graph (DAG) data structure that represents the flow of data as
+necessary for everything to be reactive. Note that this graph is *different*
+from the resource graph which is produced and sent to the engine. It is just a
+coincidence that both happen to be DAG's. (You aren't surprised when you see a
+list data structure show up in more than one place, do you?)
+
+To produce this graph, each node has a `Graph` method which it can call. This
+starts at the top most node, and is called down through the AST. The edges in
+the graphs must represent the individual expression values which are passed
+from node to node. The names of the edges must match the function type argument
+names which are used in the definition of the corresponding function. These
+corresponding functions must exist for each expression node and are produced as
+the vertices of this returned graph. This is built for the function engine.
+
+#### Function engine creation and validation
+
+Finally we have a graph of the data flows. The function engine must first
+initialize which creates references to each of the necessary function
+implementations, and gets information about each one. It then needs to be type
+checked to ensure that the data flows all correctly match what is expected. If
+you were to pass an `int` to a function expecting a `bool`, this would be a
+problem. If all goes well, the program should get run shortly.
+
+#### Function engine running and interpret
+
+At this point the function engine runs. It produces a stream of events which
+cause the `Output()` method of the top-level program to run, which produces the
+list of resources and edges. These are then transformed into the resource graph
+which is passed to the engine.
+
+### Function API
+
+If you'd like to create a built-in, core function, you'll need to implement the
+function API interface named `Func`. It can be found in
+[lang/interfaces/func.go](https://github.com/purpleidea/mgmt/tree/master/lang/interfaces/func.go).
+Your function must have a specific type. For example, a simple math function
+might have a signature of `func(x int, y int) int`. As you can see, all the
+types are known _before_ compile time.
+
+A separate discussion on this matter can be found in the [function guide](function-guide.md).
+
+What follows are each of the method signatures and a description of each.
+Failure to implement the API correctly can cause the function graph engine to
+block, or the program to panic.
+
+### Info
+
+```golang
+Info() *Info
+```
+
+The Info method must return a struct containing some information about your
+function. The struct has the following type:
+
+```golang
+type Info struct {
+	Sig  *types.Type // the signature of the function, must be KindFunc
+}
+```
+
+You must implement this correctly. Other fields in the `Info` struct may be
+added in the future. This method is usually called before any other, and should
+not depend on any other method being called first. Other methods must not depend
+on this method being called first.
+
+#### Example
+
+```golang
+func (obj *FooFunc) Info() *interfaces.Info {
+	return &interfaces.Info{
+		Sig: types.NewType("func(a str, b int) float"),
+	}
+}
+```
+
+### Init
+
+```golang
+Init(*Init) error
+```
+
+Init is called by the function graph engine to create an implementation of this
+function. It is passed in a struct of the following form:
+
+```golang
+type Init struct {
+	Hostname string // uuid for the host
+	Input  chan types.Value // Engine will close `input` chan
+	Output chan types.Value // Stream must close `output` chan
+	World  resources.World
+	Debug  bool
+	Logf   func(format string, v ...interface{})
+}
+```
+
+These values and references may be used (wisely) inside your function. `Input`
+will contain a channel of input structs matching the expected input signature
+for your function. `Output` will be the channel which you must send values to
+whenever a new value should be produced. This must be done in the `Stream()`
+function. You may carefully use `World` to access functionality provided by the
+engine. You may use `Logf` to log informational messages, however there is no
+guarantee that they will be displayed to the user. `Debug` specifies whether the
+function is running in a user-requested debug mode. This might cause you to want
+to print more log messages for example. You will need to save references to any
+or all of these info fields that you wish to use in the struct implementing this
+`Func` interface. At a minimum you will need to save `Output` as a minimum of
+one value must be produced.
+
+#### Example
+
+```golang
+Please see the example functions in
+[lang/core/](https://github.com/purpleidea/mgmt/tree/master/lang/core/).
+```
+
+### Stream
+
+```golang
+Stream(context.Context) error
+```
+
+Stream is called by the function engine when it is ready for your function to
+start accepting input and producing output. You must always produce at least one
+value. Failure to produce at least one value will probably cause the function
+engine to hang waiting for your output. This function must close the `Output`
+channel when it has no more values to send. The engine will close the `Input`
+channel when it has no more values to send. This may or may not influence
+whether or not you close the `Output` channel. You must shutdown if the input
+context cancels.
+
+#### Example
+
+```golang
+Please see the example functions in
+[lang/core/](https://github.com/purpleidea/mgmt/tree/master/lang/core/).
+```
+
+### Polymorphic Function API
+
+For some functions, it might be helpful to be able to implement a function once,
+but to have multiple polymorphic variants that can be chosen at compile time.
+For this more advanced topic, you will need to use the
+[Polymorphic Function API](#polymorphic-function-api). This will help with code
+reuse when you have a small, finite number of possible type signatures, and also
+for more complicated cases where you might have an infinite number of possible
+type signatures. (eg: `[]str`, or `[][]str`, or `[][][]str`, etc...)
+
+Suppose you want to implement a function which can assume different type
+signatures. The mgmt language does not support polymorphic types-- you must use
+static types throughout the language, however, it is legal to implement a
+function which can take different specific type signatures based on how it is
+used. For example, you might wish to add a math function which could take the
+form of `func(x int, x int) int` or `func(x float, x float) float` depending on
+the input values. You might also want to implement a function which takes an
+arbitrary number of input arguments (the number must be statically fixed at the
+compile time of your program though) and which returns a string.
+
+The `PolyFunc` interface adds additional methods which you must implement to
+satisfy such a function implementation. If you'd like to implement such a
+function, then please notify the project authors, and they will expand this
+section with a longer description of the process.
+
+#### Examples
+
+What follows are a few examples that might help you understand some of the
+language details.
+
+##### Example Foo
+
+TODO: please add an example here!
+
+##### Example Bar
+
+TODO: please add an example here!
+
+## Frequently asked questions
+
+(Send your questions as a patch to this FAQ! I'll review it, merge it, and
+respond by commit with the answer.)
+
+### What is the difference between `ExprIf` and `StmtIf`?
+
+The language contains both an `if` expression, and and `if` statement. An `if`
+expression takes a boolean conditional *and* it must contain exactly _two_
+branches (a `then` and an `else` branch) which each contain one expression. The
+`if` expression _will_ return the value of one of the two branches based on the
+conditional.
+
+#### Example:
+
+```mcl
+# this is an if expression, and both branches must exist
+$b = true
+$x = if $b {
+	42
+} else {
+	-13
+}
+```
+
+The `if` statement also takes a boolean conditional, but it may have either one
+or two branches. Branches must only directly contain statements. The `if`
+statement does not return any value, but it does produce output when it is
+evaluated. The output consists primarily of resources (vertices) and edges.
+
+#### Example:
+
+```mcl
+# this is an if statement, and in this scenario the else branch was omitted
+$b = true
+if $b {
+	file "/tmp/hello" {
+		content => "world",
+	}
+}
+```
+
+### What is the difference `types.Value.Str()` and `types.Value.String()`?
+
+In the `lang/types` library, there is a `types.Value` interface. Every value in
+our type system must implement this interface. One of the methods in this
+interface is the `String() string` method. This lets you print a representation
+of the value. You will probably never need to use this method.
+
+In addition, the `types.Value` interface implements a number of helper functions
+which return the value as an equivalent golang type. If you know that the value
+is a `bool`, you can call `x.Bool()` on it. If it's a `string` you can call
+`x.Str()`. Make sure not to call one of those type methods unless you know the
+value is of that type, or you will trigger a panic!
+
+### I created a `&ListValue{}` but it's not working!
+
+If you create a base type like `bool`, `str`, `int`, or `float`, all you need to
+do is build the `&BoolValue` and set the `V` field. Eg:
+
+```golang
+someBool := &types.BoolValue{V: true}
+```
+
+If you are building a container type like `list`, `map`, `struct`, or `func`,
+then you *also* need to specify the type of the contained values. This is
+because a list has a type of `[]str`, or `[]int`, or even `[][]foo`. Eg:
+
+```golang
+someListOfStrings := &types.ListValue{
+	T: types.NewType("[]str"),	# must match the contents!
+	V: []types.Value{
+		&types.StrValue{V: "a"},
+		&types.StrValue{V: "bb"},
+		&types.StrValue{V: "ccc"},
+	},
+}
+```
+
+If you don't build these properly, then you will cause a panic! Even empty lists
+have a type.
+
+### Is the `class` statement a singleton?
+
+Not really, but practically it can be used as such. The `class` statement is not
+a singleton since it can be called multiple times in different locations, and it
+can also be parameterized and called multiple times (with `include`) using
+different input parameters. The reason it can be used as such is that statement
+output (from multple classes) that is compatible (and usually identical) will
+be automatically collated and have the duplicates removed. In that way, you can
+assume that an unparameterized class is always a singleton, and that
+parameterized classes can often be singletons depending on their contents and if
+they are called in an identical way or not. In reality the de-duplication
+actually happens at the resource output level, so anything that produces
+multiple compatible resources is allowed.
+
+### Are recursive `class` definitions supported?
+
+Recursive class definitions where the contents of a `class` contain a
+self-referential `include`, either directly, or with indirection via any other
+number of classes is not supported. It's not clear if it ever will be in the
+future, unless we decide it's worth the extra complexity. The reason is that our
+FRP actually generates a static graph which doesn't change unless the code does.
+To support dynamic graphs would require our FRP to be a "higher-order" FRP,
+instead of the simpler "first-order" FRP that it is now. You might want to
+verify that I got the [nomenclature](https://github.com/gelisam/frp-zoo)
+correct. If it turns out that there's an important advantage to supporting a
+higher-order FRP in mgmt, then we can consider that in the future.
+
+I realized that recursion would require a static graph when I considered the
+structure required for a simple recursive class definition. If some "depth"
+value wasn't known statically by compile time, then there would be no way to
+know how large the graph would grow, and furthermore, the graph would need to
+change if that "depth" value changed.
+
+### I don't like the mgmt language, is there an alternative?
+
+Yes, the language is just one of the available "frontends" that passes a stream
+of graphs to the engine "backend". While it _is_ the recommended way of using
+mgmt, you're welcome to either use an alternate frontend, or write your own. To
+write your own frontend, you must implement the
+[GAPI](https://github.com/purpleidea/mgmt/blob/master/gapi/gapi.go) interface.
+
+### I'm an expert in FRP, and you got it all wrong; even the names of things!
+
+I am certainly no expert in FRP, and I've certainly got lots more to learn. One
+thing FRP experts might notice is that some of the concepts from FRP are either
+named differently, or are notably absent.
+
+In mgmt, we don't talk about behaviours, events, or signals in the strict FRP
+definitons of the words. Firstly, because we only support discretized, streams
+of values with no plan to add continuous semantics. Secondly, because we prefer
+to use terms which are more natural and relatable to what our target audience is
+expecting. Our users are more likely to have a background in Physiology, or
+systems administration than a background in FRP.
+
+Having said that, we hope that the FRP community will engage with us and help
+improve the parts that we got wrong. Even if that means adding continuous
+behaviours!
+
+### This is brilliant, may I give you a high-five?
+
+Thank you, and yes, probably. "Props" may also be accepted, although patches are
+preferred. If you can't do either, [donations](https://purpleidea.com/misc/donate/)
+to support the project are welcome too!
+
+### Where can I find more information about mgmt?
+
+Additional blog posts, videos and other material
+[is available!](https://github.com/purpleidea/mgmt/blob/master/docs/on-the-web.md).
+
+## Suggestions
+
+If you have any ideas for changes or other improvements to the language, please
+let us know! We're still pre 1.0 and pre 0.1 and happy to change it in order to
+get it right!

docs/on-the-web.md

@@ -0,0 +1,61 @@
+# On the web
+
+Here is a list of places mgmt has appeared on the web. Feel free to send a patch
+if we missed something that you think is relevant!
+
+## Links
+
+| Author | Format | Subject |
+|---|---|---|
+| James Shubin | blog | [Next generation configuration mgmt](https://purpleidea.com/blog/2016/01/18/next-generation-configuration-mgmt/) |
+| James Shubin | video | [Introductory recording from DevConf.cz 2016](https://www.youtube.com/watch?v=GVhpPF0j-iE&html5=1) |
+| James Shubin | video | [Introductory recording from CfgMgmtCamp.eu 2016](https://www.youtube.com/watch?v=fNeooSiIRnA&html5=1) |
+| Julian Dunn | video | [On mgmt at CfgMgmtCamp.eu 2016](https://www.youtube.com/watch?v=kfF9IATUask&t=1949&html5=1) |
+| Walter Heck | slides | [On mgmt at CfgMgmtCamp.eu 2016](http://www.slideshare.net/olindata/configuration-management-time-for-a-4th-generation/3) |
+| Marco Marongiu | blog | [On mgmt](http://syslog.me/2016/02/15/leap-or-die/) |
+| Felix Frank | blog | [From Catalog To Mgmt (on puppet to mgmt "transpiling")](https://ffrank.github.io/features/2016/02/18/from-catalog-to-mgmt/) |
+| James Shubin | blog | [Automatic edges in mgmt (...and the pkg resource)](https://purpleidea.com/blog/2016/03/14/automatic-edges-in-mgmt/) |
+| James Shubin | blog | [Automatic grouping in mgmt](https://purpleidea.com/blog/2016/03/30/automatic-grouping-in-mgmt/) |
+| John Arundel | tweet | [“Puppet’s days are numbered.”](https://twitter.com/bitfield/status/732157519142002688) |
+| Felix Frank | blog | [Puppet, Meet Mgmt (on puppet to mgmt internals)](https://ffrank.github.io/features/2016/06/12/puppet,-meet-mgmt/) |
+| Felix Frank | blog | [Puppet Powered Mgmt (puppet to mgmt tl;dr)](https://ffrank.github.io/features/2016/06/19/puppet-powered-mgmt/) |
+| James Shubin | blog | [Automatic clustering in mgmt](https://purpleidea.com/blog/2016/06/20/automatic-clustering-in-mgmt/) |
+| James Shubin | video | [Recording from CoreOSFest 2016](https://www.youtube.com/watch?v=KVmDCUA42wc&html5=1) |
+| James Shubin | video | [Recording from DebConf16](http://meetings-archive.debian.net/pub/debian-meetings/2016/debconf16/Next_Generation_Config_Mgmt.webm) ([Slides](https://annex.debconf.org//debconf-share/debconf16/slides/15-next-generation-config-mgmt.pdf)) |
+| Felix Frank | blog | [Edging It All In (puppet and mgmt edges)](https://ffrank.github.io/features/2016/07/12/edging-it-all-in/) |
+| Felix Frank | blog | [Translating All The Things (puppet to mgmt translation warnings)](https://ffrank.github.io/features/2016/08/19/translating-all-the-things/) |
+| James Shubin | video | [Recording from systemd.conf 2016](https://www.youtube.com/watch?v=jB992Zb3nH0&html5=1) |
+| James Shubin | blog | [Remote execution in mgmt](https://purpleidea.com/blog/2016/10/07/remote-execution-in-mgmt/) |
+| James Shubin | video | [Recording from High Load Strategy 2016](https://vimeo.com/191493409) |
+| James Shubin | video | [Recording from NLUUG 2016](https://www.youtube.com/watch?v=MmpwOQAb_SE&html5=1) |
+| James Shubin | blog | [Send/Recv in mgmt](https://purpleidea.com/blog/2016/12/07/sendrecv-in-mgmt/) |
+| Julien Pivotto | blog | [Augeas resource for mgmt](https://roidelapluie.be/blog/2017/02/14/mgmt-augeas/) |
+| James Shubin | blog | [Metaparameters in mgmt](https://purpleidea.com/blog/2017/03/01/metaparameters-in-mgmt/) |
+| James Shubin | video | [Recording from Incontro DevOps 2017](https://vimeo.com/212241877) |
+| Yves Brissaud | blog | [mgmt aux HumanTalks Grenoble (french)](http://log.winsos.net/2017/04/12/mgmt-aux-human-talks-grenoble.html) |
+| James Shubin | video | [Recording from OSDC Berlin 2017](https://www.youtube.com/watch?v=LkEtBVLfygE&html5=1) |
+| Jonathan Gold | blog | [AWS:EC2 in mgmt](https://jonathangold.ca/blog/aws-ec2-in-mgmt/) |
+| James Shubin | video | [Recording from OSMC Nuremberg 2017](https://www.youtube.com/watch?v=hSVadQLeplU&html5=1) |
+| James Shubin | video | [Recording from LCA 2018, Developers Miniconf](https://www.youtube.com/watch?v=OvgGfW0ilbE) |
+| James Shubin | video | [Recording from LCA 2018, Sysadmin Miniconf](https://www.youtube.com/watch?v=ELq1XOJMIPY) |
+| James Shubin | video | [Recording from LCA 2018, Main Conference](https://www.youtube.com/watch?v=_9PG64AOQ3w) |
+| James Shubin | video | [Recording from DevConf.cz 2017](https://www.youtube.com/watch?v=-FPEK08l1Zk) |
+| James Shubin | video | [Recording from FOSDEM 2018, Config Management Devroom](https://video.fosdem.org/2018/UA2.114/mgmt.webm) |
+| James Shubin | blog | [Mgmt Configuration Language](https://purpleidea.com/blog/2018/02/05/mgmt-configuration-language/) |
+| James Shubin | video | [Recording from CfgMgmtCamp.eu 2018](https://www.youtube.com/watch?v=NxObmwZDyrI) |
+| Jonathan Gold | blog | [Go Netlink and Select](https://jonathangold.ca/blog/go-netlink-and-select/) |
+| James Shubin | video | [Recording from DevOpsDays Montreal 2018](https://www.youtube.com/watch?v=1i38c5cooHo) |
+| James Shubin | video | [Recording from FOSDEM Minimalistic Languages Devroom 2019](https://video.fosdem.org/2019/K.4.201/mgmtconfig.webm) |
+| James Shubin | video | [Recording from FOSDEM Infra Management Devroom 2019](https://video.fosdem.org/2019/UB2.252A/mgmt.webm) |
+| James Shubin | video | [Recording from FOSDEM Graph Processing Devroom 2019](https://video.fosdem.org/2019/H.1308/graph_mgmt_config.webm) |
+| James Shubin | video | [Recording from FOSDEM Virtualization Devroom 2019](https://video.fosdem.org/2019/H.2213/vai_real_time_virtualization_automation.webm) |
+| James Shubin | video | [Recording from FOSDEM Containers Devroom 2019](https://video.fosdem.org/2019/UA2.114/containers_mgmt.webm) |
+| James Shubin | video | [Recording from FOSDEM Monitoring Devroom 2019](https://video.fosdem.org/2019/UB2.252A/real_time_merging_of_config_management_and_monitoring.webm) |
+| James Shubin | blog | [Mgmt Configuration Language: Class and Include](https://purpleidea.com/blog/2019/07/26/class-and-include-in-mgmt/) |
+| James Shubin | video | [Recording from FOSDEM 2020, Main Track (History)](https://video.fosdem.org/2020/Janson/automation.webm) |
+| James Shubin | video | [Recording from FOSDEM 2020, Infra Management Devroom](https://video.fosdem.org/2020/UA2.120/mgmt.webm) |
+| James Shubin | video | [Recording from FOSDEM 2020, Minimalistic Languages Devroom](https://video.fosdem.org/2020/AW1.125/mgmtconfigmore.webm) |
+| James Shubin | video | [Recording from CfgMgmtCamp.eu 2020](https://www.youtube.com/watch?v=Kd7FAORFtsc) |
+| James Shubin | video | [Recording from CfgMgmtCamp.eu 2023](https://www.youtube.com/watch?v=FeRGRj8w0BU) |
+| James Shubin | video | [Recording from FOSDEM 2024, Golang Devroom](https://video.fosdem.org/2024/ud2218a/fosdem-2024-2575-single-binary-full-stack-provisioning.mp4) |
+| James Shubin | video | [Recording from CfgMgmtCamp.eu 2024](https://www.youtube.com/watch?v=vBt9lpGD4bc) |

docs/prometheus.md

@@ -0,0 +1,66 @@
+# Prometheus support
+
+Mgmt comes with a built-in prometheus support. It is disabled by default, and
+can be enabled with the `--prometheus` command line switch.
+
+By default, the prometheus instance will listen on [`127.0.0.1:9233`][pd]. You
+can change this setting by using the `--prometheus-listen` cli option:
+
+To have mgmt prometheus bind interface on 0.0.0.0:45001, use:
+`./mgmt r --prometheus --prometheus-listen :45001`
+
+## Metrics
+
+Mgmt exposes three kinds of resources: _go_ metrics, _etcd_ metrics and _mgmt_
+metrics.
+
+### go metrics
+
+We use the [prometheus go_collector][pgc] to expose go metrics. Those metrics
+are mainly useful for debugging and perf testing.
+
+### etcd metrics
+
+mgmt exposes etcd metrics. Read more in the [upstream documentation][etcdm]
+
+### mgmt metrics
+
+Here is a list of the metrics we provide:
+
+- `mgmt_resources_total`: The number of resources that mgmt is managing
+- `mgmt_checkapply_total`: The number of CheckApply's that mgmt has run
+- `mgmt_failures_total`: The number of resources that have failed
+- `mgmt_failures`: The number of resources that have failed
+- `mgmt_graph_start_time_seconds`: Start time of the current graph since unix
+epoch in seconds
+
+For each metric, you will get some extra labels:
+
+- `kind`: The kind of mgmt resource
+
+For `mgmt_checkapply_total`, those extra labels are set:
+
+- `eventful`: "true" or "false", if the CheckApply triggered some changes
+- `errorful`: "true" or "false", if the CheckApply reported an error
+- `apply`: "true" or "false", if the CheckApply ran in apply or noop mode
+
+## Alerting
+
+You can use prometheus to alert you upon changes or failures. We do not provide
+such templates yet, but we plan to provide some examples in this repository.
+Patches welcome!
+
+## Grafana
+
+We do not have grafana dashboards yet. Patches welcome!
+
+## External resources
+
+- [prometheus website](https://prometheus.io/)
+- [prometheus documentation](https://prometheus.io/docs/introduction/overview/)
+- [prometheus best practices regarding metrics naming](https://prometheus.io/docs/practices/naming/)
+- [grafana website](http://grafana.org/)
+
+[pgc]: https://github.com/prometheus/client_golang/blob/master/prometheus/go_collector.go
+[etcdm]: https://coreos.com/etcd/docs/latest/metrics.html
+[pd]: https://github.com/prometheus/prometheus/wiki/Default-port-allocations

docs/quick-start-guide.md

@@ -0,0 +1,128 @@
+# Quick start guide
+
+## Introduction
+
+This guide is intended for users and developers. If you're brand new to `mgmt`,
+it's probably a good idea to start by reading an
+[introductory article about the engine](https://purpleidea.com/blog/2016/01/18/next-generation-configuration-mgmt/)
+and an [introductory article about the language](https://purpleidea.com/blog/2018/02/05/mgmt-configuration-language/).
+[There are other articles and videos available](on-the-web.md) if you'd like to
+learn more or prefer different formats. Once you're familiar with the general
+idea, or if you prefer a hands-on approach, please start hacking...
+
+## Getting mgmt
+
+You can either build `mgmt` from source, or you can download a pre-built
+release. There are also some distro repositories available, but they may not be
+up to date. A pre-built release is the fastest option if there's one that's
+available for your platform. If you are developing or testing a new patch to
+`mgmt`, or there is not a release available for your platform, then you'll have
+to build your own.
+
+### Downloading a pre-built release:
+
+This method is not recommended because those packages are now very old.
+
+The latest releases can be found [here](https://github.com/purpleidea/mgmt/releases/).
+An alternate mirror is available [here](https://dl.fedoraproject.org/pub/alt/purpleidea/mgmt/releases/).
+
+Make sure to verify the signatures of all packages before you use them. The
+signing key can be downloaded from [https://purpleidea.com/contact/#pgp-key](https://purpleidea.com/contact/#pgp-key)
+to verify the release.
+
+If you've decided to install a pre-build release, you can skip to the
+[Running mgmt](#running-mgmt) section below!
+
+### Building a release:
+
+You'll need some dependencies, including `golang`, and some associated tools.
+
+#### Installing golang
+
+* You need golang version 1.20 or greater installed.
+	* To install on rpm style systems: `sudo dnf install golang`
+	* To install on apt style systems: `sudo apt install golang`
+	* To install on macOS systems install [Homebrew](https://brew.sh)
+	and run: `brew install go`
+* You can run `go version` to check the golang version.
+* If your distro is too old, you may need to [download](https://golang.org/dl/)
+a newer golang version.
+
+#### Setting up golang
+
+* You can skip this step, as your installation will default to using `~/go/`,
+but if you do not have a `GOPATH` yet and want one in a custom location, create
+one and export it:
+
+```shell
+mkdir $HOME/gopath
+export GOPATH=$HOME/gopath
+```
+
+* You might also want to add the GOPATH to your `~/.bashrc` or `~/.profile`.
+* For more information you can read the
+[GOPATH documentation](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable).
+
+#### Getting the mgmt code and associated dependencies
+
+* Download the `mgmt` code and switch to that directory:
+
+```shell
+git clone --recursive https://github.com/purpleidea/mgmt/ ~/mgmt/
+cd ~/mgmt/
+```
+
+* Add `$GOPATH/bin` to `$PATH`
+
+```shell
+export PATH=$PATH:$GOPATH/bin
+```
+
+* Run `make deps` to install system and golang dependencies. Take a look at
+`misc/make-deps.sh` if you want to see the details of what it does.
+
+#### Building mgmt
+
+* Now run `make` to get a freshly built `mgmt` binary. If this succeeds, you can
+proceed to the [Running mgmt](#running-mgmt) section below!
+
+### Installing a distro release
+
+Installation of `mgmt` from distribution packages currently needs improvement.
+They are not always up-to-date with git master and as such are not recommended.
+At the moment we have:
+* [COPR](https://copr.fedoraproject.org/coprs/purpleidea/mgmt/) (currently dead)
+* [Arch](https://aur.archlinux.org/packages/mgmt/) (currently stale)
+
+Please contribute more and help improve these! We'd especially like to see a
+Debian package!
+
+### Building from a container:
+
+This method avoids polluting your workstation with the dependencies for the
+build. Here is an example using Fedora, Podman and Buildah:
+
+```shell
+git clone --recursive https://github.com/purpleidea/mgmt/ ~/mgmt/
+cd ~/mgmt/docker
+buildah build -f Dockerfile-fedora.build -t mgmt_build
+podman run -d -it --name mgmt_build localhost/mgmt_build
+podman cp mgmt_build:/src/github.com/purpleidea/mgmt/mgmt /tmp/mgmt
+sudo mv /tmp/mgmt /usr/local/bin  # be sure this is in your $PATH
+sudo chown root:root /usr/local/bin/mgmt
+```
+
+## Running mgmt
+
+* Run `mgmt run --tmp-prefix lang examples/lang/hello0.mcl` to try out a very
+simple example! If you built it from source, you'll need to use `./mgmt` from
+the project directory.
+* Look in that example file that you ran to see if you can figure out what it
+did! You can press `^C` to exit `mgmt`.
+* Have fun hacking on our future technology and get involved to shape the
+project!
+
+## Examples
+
+Please look in the [examples/lang/](../examples/lang/) folder for some more
+examples!

docs/release-notes/0.0.10

@@ -0,0 +1,51 @@
+I've just released version 0.0.10 of mgmt!
+
+NEWS
+
+57 files changed, 1991 insertions(+), 752 deletions(-)
+
+* There's a new resource called `KV`. Short examples exist, but I
+haven't yet published a whole integration showing the usefulness.
+
+* A major race was fixed. The issue of what to do with BackPokes during
+start/pause was never previously solved. I had this as an open issue on
+my whiteboard for a while, and I finally got some time to work through
+it. The answer wasn't that difficult, but I think it was shrouded in
+some tunnel vision. See the commit messages and source comments for the
+details.
+
+* The GAPI grew four new associated World API methods: StrWatch,
+StrGet, StrSet, StrDel, and the associated etcd backed implementations.
+These are quite useful when combined with the KV resource.
+
+* There are now P/V style counting semaphores available as metaparams.
+This is particularly cool because the implementation is (AFAIK,
+assuming no bugs) dead-lock free! This is mentioned in my recent blog
+post.
+
+* See the git log for more NEWS, and sorry for anything notable I left
+out!
+
+BUGS
+
+* There's a `concurrent map write` bug in the semaphore implementation
+which is fixed in git master. Since it was a race, it was only caught
+after this release was made. I should also figure out if the sema check
+should go after the BackPoke or not.
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started!
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+James Shubin, Julien Pivotto, Michael Borden.
+We had 3 unique committers since 0.0.9, and have had 30 overall.
+
+Happy hacking,
+James

docs/release-notes/0.0.11

@@ -0,0 +1,59 @@
+I've just released version 0.0.11 of mgmt!
+
+NEWS
+
+ 20 files changed, 579 insertions(+), 126 deletions(-)
+
+* Added a missing mutex around the semaphore map which prevents
+occasional panics
+
+* Removed exec pollint param which is not needed because of the poll
+metaparam
+
+* Fixed a state rechecking bug in exec resource (things are faster now)
+
+* Fixed the major annoyance of exec resources receiving main's signals.
+If we would ^C the main mgmt, the child processes would receive this
+too which was incorrect.
+
+* Fixed the deadlock on resource errors. This meant that previously if
+a resource failed, we would deadlock the graph from shutting down. This
+was bad and I'm glad it's now fixed. Sorry about that!
+
+* Improved the backpoke logic to not require semaphores since we used
+to take the lock even when we were going to backpoke which was
+unnecessary.
+
+* Added fast pausing to the graph. This means that a ^C or a pause
+transition used to wait for the whole graph to roll through, but it now
+finishes after the currently running resources finish executing. Read
+the commit messages for more background here including the discussion
+about a possible Interrupt() addition to the resource API.
+
+* Prometheus support has been updated!
+
+* See the git log for more NEWS, and sorry for anything notable I left
+out!
+
+BUGS
+
+* We're in pretty good shape now. There are some small issues, but
+nothing major that I don't know about.
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started!
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+James Shubin, Julien Pivotto
+We had 2 unique committers since 0.0.10, and have had 30 overall.
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.12

@@ -0,0 +1,87 @@
+I've just released version 0.0.12 of mgmt!
+
+Sorry if I've been more quiet than usual, I've had to focus a lot of my
+time on GlusterFS related features ($dayjob official directives) and
+work there.
+
+One goal is to try and use libmgmt to either wholly or partially re-
+implement glusterd. As a result, a lot of my upstream focus has been
+re-prioritized to features needed for that effort.
+
+I wrote a PoC called gd3: https://github.com/purpleidea/gd3
+(It has now bit-rotted compared to upstream mgmt, but is easy to fix.)
+The initial scope looks like it will be much smaller, but hopefully
+this is interesting to you too. Ping me if you'd like to help.
+
+We desperately need your contributions if we're going to get mgmt
+standalone into a MVP. To motivate you, there's some great new stuff
+that landed since 0.0.11, including:
+
+* a great new YAML parser from contributor Mildred
+
+* a huge pgraph refactor (to remove internal deps and cycles)
+
+* a great amount of new tests and testing
+
+and so much more...
+
+NEWS
+
+ 76 files changed, 7549 insertions(+), 4269 deletions(-)
+
+* The svc resource now also supports user services
+
+* There's a fabulous new yaml parser that fixes a longstanding issue in
+my original code. Try it with --yaml2. I'll remove the old one
+eventually. Thanks to contributor Mildred for this great work!
+
+* Refactored the lib/ etcd usage into the GAPI's for a cleaner main
+
+* World API grew some new methods for libmgmt users
+
+* pgraph refactor and cleanup, now it's a fairly clean standalone pkg
+
+* pgraph functions to flatten/merge in subgraphs along with examples
+
+* Giant resource refactor to hopefully make things more logical, and to
+simplify the resource API. This also introduces the mgraph struct to
+add the higher level graph knowledge outside of pgraph.
+
+* A partial implementation of a "Graph" (recursive subgraph?) resource!
+See the code for details, as help is wanted to finish this. This should
+help elucidate what the most elegant design for the mgmt core should
+be.
+
+* Send/Recv support for the exec resource as output, stdout, and stderr
+
+* GAPI improvements to support exit requests and fast pausing
+
+* AutoEdge API improvements including a fix+test for a regression
+
+* A possible fix for the possible etcd server startup race
+
+* A fun amount of new tests all over including for gometalinter
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+BUGS
+
+* We fixed a bunch of stuff, and added more tests!
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started!
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+James Shubin, Julien Pivotto, Mildred Ki'Lya
+We had 3 unique committers since 0.0.11, and have had 30 overall.
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.13

@@ -0,0 +1,89 @@
+I've just released version 0.0.13 of mgmt!
+
+I guess this is an appropriate number for a scary October release.
+
+We recently re-licensed to the more permissive GPL. I put a lot of
+thought into it, and also wrote up a short blog post about some of the
+reasoning. It's here:
+
+https://ttboj.wordpress.com/2017/10/17/copyleft-is-dead-long-live-copyl
+eft/
+
+If you read to the end you'll also see that Red Hat is not funding my
+mgmt work anymore. This is too bad, and means I'll only have small
+amounts of personal time available to work on this. If you'd like to
+help fund my work, or know someone who'd like to, please let me know!
+
+Having said that, there's some great new stuff that landed since
+0.0.12, including:
+
+* new resources from new contributor Jonathan Gold (aws, group, user)
+
+* an HCL frontend from new contributor Chris McKenzie
+
+* polish in a number of places including in the nspawn resource
+
+and so much more... If you'd prefer to have releases more often, then
+please let me know! Lastly, the language and a number of associated
+parts are on its way. I hope to push this monster patch to git master
+before February.
+
+It's also worth mentioning that we have 17 resources now! wow.
+
+NEWS
+
+ 140 files changed, 3921 insertions(+), 848 deletions(-)
+
+* Many improvements to tests, testing and small fixes to avoid false-
+failures on travis.
+
+* golint now reports 0 issues.
+
+* An HCL frontend if you'd prefer that to the YAML. Also a great
+example of how to plug in a new frontend.
+
+* An update to golang 1.8 as the minimum version required.
+
+* Bump the etcd version to 3.2.6+ -- Looking forward to a 3.3 release
+which should probably include some patches we upstreamed.
+
+* Addition of new user and group resources. These also include a bunch
+of automatic edges.
+
+* Addition of an AWS resource! I've wanted this for a while, as it
+demonstrates nicely how event based cloud resources can fit nicely into
+our design. There's still a lot to do, and we have some suggestions for
+Amazon too. If you have a contact there, please put me in touch!
+
+* Our nspawn resource is more polished now.
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started!
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved. This is free and friendly. You get to improve your skills,
+and we get some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+AdnanLFC, Arthur Mello, ChrisMcKenzie, Dennis Kliban, Ismael Puerto,
+James Shubin, Jonathan Gold, Juan Luis de Sousa-Valadas Castaño, Juan-
+Luis de Sousa-Valadas Castaño (although I suspect the last two are the
+same ;))
+
+We had 9 unique committers since 0.0.12, and have had 38 overall.
+Run 'git log 0.0.12..0.0.13' to see what has changed since 0.0.12
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.14

@@ -0,0 +1,81 @@
+I've just released version 0.0.14 of mgmt!
+
+> 118 files changed, 2688 insertions(+), 974 deletions(-)
+
+There's some great new stuff that landed since
+0.0.13, including:
+
+* amazon AWS EC2 resource is now in git master.
+
+* more automatic edges from new contributor Guillaume Herail (xiu)
+
+* a move to golang 1.8 or higher
+
+and so much more... This will probably be the last release before the
+language lands in git master. It's a pretty giant patch coming :/
+
+NEWS
+
+* We're > 1k stars on GitHub now. It's a silly metric, but ¯\_(ツ)_/¯
+
+* Jonathan Gold has done a lot of hard work on the AWS EC2 resource,
+and it's now in git master. There are still many things we'd like to
+do, but it's a great start on what is a *monster* resource, and
+hopefully it will inspire others to get involved.
+
+In particular, it was a great learning experience (for me in
+particular!) about how bad the EC2 golang API is. There are some
+notable design bugs we found, and if anyone from Amazon engineering
+would like to reach out to us, we'd love to provide some constructive
+ideas.
+
+* Guillaume Herail (xiu) wrote some really nice patches, and picked up
+on the autoedges API very quickly. Hopefully he'll have time to work on
+even more!
+
+* Paul Morgan sent us some nice shell fixups-- many more exist in an
+open PR that didn't make it into this release. Hopefully we'll get
+those merged by 0.0.15
+
+* Felix Frank did a few Puppet compiler fix ups. I think he's been
+refreshing his work with new resources recently...
+
+* We're looking for help writing Google, DigitalOcean, Rackspace, etc
+resources if anyone is interested, reach out to us. Particularly if
+there is support from those organizations as well.
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+EVENTS
+
+There are a bunch of upcoming mgmt talks and events! Stay tuned for
+details in the coming email, but TL;DR: Linux Conf Australia, FOSDEM, &
+CfgMgmtCamp.eu -- from three different speakers, and including a
+hackathon too!
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started! Expect many new tagged #mgmtlove
+issues within the month.
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved. This is free and friendly. You get to improve your skills,
+and we get some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+Felix Frank, Guillaume Herail, James Shubin, Jonathan Gold,
+jonathangold, Julien Pivotto, Paul Morgan, Toshaan Bharvani
+We had 8 unique committers since 0.0.13, and have had 41 overall.
+run 'git log 0.0.13..0.0.14' to see what has changed since 0.0.13
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.15

@@ -0,0 +1,116 @@
+I've just released version 0.0.15 of mgmt!
+
+> 328 files changed, 29869 insertions(+), 943 deletions(-)
+
+(Yeah, that's almost 30k+ LOC)
+
+There's some great new stuff that landed since 0.0.14, including:
+
+* THE LANGUAGE (mcl)
+
+* "Deploys": a distributed way to push code into your cluster
+
+* Scheduling (as a reactive function)
+
+* Better testing
+
+* a move to etcd 3.3+ and golang 1.9+
+
+and so much more... This is a monster release. Please try out the
+language and all the other new features today :)
+
+NEWS
+
+* We released the language. Please play around with it :) It's time to
+get used to this cool new paradigm. Learn more from the...
+
+Blog post:
+https://purpleidea.com/blog/2018/02/05/mgmt-configuration-language/
+
+Video:
+https://www.youtube.com/watch?v=NxObmwZDyrI
+
+Docs:
+https://github.com/purpleidea/mgmt/blob/master/docs/language-guide.md
+
+Function guide:
+https://github.com/purpleidea/mgmt/blob/master/docs/function-guide.md
+
+And tons of code all over git master. Check the lang/ folder.
+
+* There is a reactive scheduler in the language. Use your imagination,
+or play around with:
+https://github.com/purpleidea/mgmt/blob/3ad7097c8aa7eab7f895aab9af22338
+c0cf82986/lang/funcs/core/schedule_polyfunc.go#L18
+
+* There is a "deploys" feature. It's not documented yet. You should
+poke around if you're curious. Consider this an early soft release.
+
+* There is a FS implementation to store files in a POSIX-like layer on
+top of etcd. It's used by deploys. It needs more tests though :)
+
+* The language grew two "simple" API's for implementing functions, so
+that new functionality can be exposed in the mgmt language.
+
+* The language grew two ways to specify edges between resources: either
+internal to the resource, or externally as standalone edges.
+
+* The language now supports optional resource parameters via the
+"elvis" operator. This keeps things type safe and avoids needing an
+"undef" or "nil" in the language. This operator also works for edge
+declarations.
+
+* New contributor Johan Bloemberg has been on fire sending patches!
+He has already made some great improvements to our Makefile for
+testing, and the addition of the env* functions in the language, with
+much more code pending in open PR's.
+
+* Initial debian packaging has been added. It now needs a maintainer to
+build, upload, and love it :)
+
+* We have an early emacs major mode for "mcl", our language.
+
+* Lots of new documentation has been added. Particularly for developers
+wanting to contribute to the project.
+
+* We're looking for help writing Google, DigitalOcean, Rackspace, etc
+resources if anyone is interested, reach out to us. Particularly if
+there is support from those organizations as well.
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started! For details please see:
+
+https://github.com/purpleidea/mgmt/blob/master/docs/faq.md#how-do-i-con
+tribute-to-the-project-if-i-dont-know-golang
+
+Many new tagged #mgmtlove issues were tagged:
+https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%
+3Amgmtlove
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved.
+This is free and friendly. You get to improve your skills,
+and we get
+some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+Carsten Thiel, dsx, James Shubin, Joe Julian, Johan Bloemberg, Jonathan
+Gold, jonathangold, karimb, Oliver Frommel, Peter Oliver, Toshaan
+Bharvani, Wim
+We had 12 unique committers since 0.0.14, and have had 48 overall.
+run 'git log 0.0.14..0.0.15' to see what has changed since 0.0.14
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.16

@@ -0,0 +1,104 @@
+I've just released version 0.0.16 of mgmt!
+
+> 220 files changed, 14243 insertions(+), 9491 deletions(-)
+
+Woo...
+
+There's some great new stuff that landed since 0.0.15, including:
+
+* A giant engine re-write! (Makes resource writing more elegant too.)
+
+* New resources!!
+
+* New language features!!!
+
+and so much more... This is a monster release. Please try out the new
+features today :)
+
+NEWS
+
+* New resources include: net, mount and docker:container. Jonathan was
+responsible for all of these. Please take them for a spin! He's looking
+for a job too, and would probably be happy to get paid to work on mgmt.
+
+* We're > 1.5k stars on GitHub now. It's a silly metric, but ¯\_(ツ)_/¯
+
+* A giant engine refactoring/re-write was done. This cleaned up the
+code significantly, and made it more elegant to write resources.
+Unfortunately there is one small bug that I missed and that I haven't
+fixed yet. It rarely happens except during some of our tests during
+shutdown, which causes intermittent failures. It shouldn't block you
+playing with mgmt.
+
+* The language "class" and "include" statements have been added. These
+are important pieces for writing reusable modules which are coming
+soon. Try them out! (This comes with a bunch of tests too.)
+
+* We have an integration testing framework. It's pretty cool, it spins
+up a full mgmt cluster and runs stuff. Try it out or add some tests.
+
+* I had fun fixing a big bug: 06ee05026b0c743d19c7d62675f8ddeabdc8dd4f
+
+* I removed the remote execution functionality from core. I realized it
+could be re-written as a resource, and it was also in the way from some
+other cleanups that were more important. Half the new code is done,
+ping me if this is a priority for you or you want to help.
+
+* I also removed the HCL front-end, because mcl is usable enough to be
+more fun to play with, and I wanted to refactor some code. If someone
+really wants it back, let me know.
+
+* We have some release building scripts in git master, so you can now
+download pre-built (with fpm) RPM, DEB, or PACMAN packages! They're
+signed too. https://github.com/purpleidea/mgmt/releases/tag/0.0.16
+
+* We're looking for help writing Google, DigitalOcean, Rackspace, etc
+resources if anyone is interested, reach out to us. Particularly if
+there is support from those organizations as well.
+
+* Many other bug fixes, changes, etc...
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+MISC
+
+I took a bit of a break recently to catch up on some life stuff, but I
+think I'm back on track. While git master hasn't been especially busy,
+there's an active feature branch at feat/import which contains some fun
+stuff, with a very WIP giant patch still sitting on my machine. I hope
+to finish it up soon and then do another release. That branch contains
+one of the last big features before I'll really be ready to run mgmt on
+my personal servers!
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started! For details please see:
+
+https://github.com/purpleidea/mgmt/blob/master/docs/faq.md#how-do-i-con
+tribute-to-the-project-if-i-dont-know-golang
+
+Many new tagged #mgmtlove issues were tagged:
+https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%
+3Amgmtlove
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved.
+This is free and friendly. You get to improve your skills,
+and we get
+some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+Alan Jenkins, James Shubin, jesus m. rodriguez, Jonathan Gold,
+jonathangold, Lauri Ojansivu, phaer
+We had 7 unique committers since 0.0.15, and have had 52 overall.
+run 'git log 0.0.15..0.0.16' to see what has changed since 0.0.15
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.17

@@ -0,0 +1,111 @@
+I've just released version 0.0.17 of mgmt!
+
+> 269 files changed, 13281 insertions(+), 1633 deletions(-)
+
+There's some very useful stuff that landed since 0.0.16, including:
+
+* Modules and import system now exists!
+* A lot of tests, fixes and a huge new test infra was added
+* Merging puppet with mcl code is now possible (madness!)
+* We made a small change to the cli UI
+* Bump to golang 1.10 (please update your environments)
+
+And much more...
+
+DOWNLOAD
+
+Prebuilt binaries are available here:
+https://github.com/purpleidea/mgmt/releases/tag/0.0.17
+
+NEWS
+
+* One of the biggest missing features was the lack of a module/import
+system. After some initial exploration on what turned out to be a dead-
+end, I found what I think is a very elegant approach, which is now in
+this release. Please try it out, there are docs available. I hope to
+write a blog post about it soon.
+
+(There's one additional "kind" of import that I'm considering, similar
+to a macro "#include", that I might add. To be determined. Let me know
+if you find anything missing as of today.)
+
+* Felix added the first version of his mcl+puppet frontend. This should
+allow you to more cleverly merge legacy puppet environments with mcl
+code. It's fantastic, take a look.
+
+* Jonathan added a systemd-timer resource. This is a great replacement
+for cron.
+
+* We changed the CLI ui to improve the determinism of the frontend
+selection. Basically we changed from: `mgmt run --lang code.mcl` to:
+`mgmt run lang --lang code.mcl`. Remember to put --tmp-prefix after
+`run` directly where it is used.
+
+* We made a whole bunch of cleanups to the test infra, added new test
+infra for testing complex mcl modules and the import/module system, and
+of course added new tests.
+
+* You can pass a list of strings as the resource name to build that
+many resources. (Looping/iteration!)
+
+* You can specify all the metaparams and auto-* properties in mcl now.
+
+* Native mcl code can be used to write imported core code.
+
+* There was a bug that snuck into the pkg res. This has now been fixed.
+
+* A small, long-time copy+pasta error bug was fixed in Exec.
+
+* Virtually all the imports of the "log" package are at the top-level
+now. This will make moving to a new logger easier in the future. I have
+an innovative logger idea that I have a design for that I'll eventually
+get to.
+
+* A few workarounds for occasional test failures were added. Some
+legacy code needs a cleanup, and it's not done yet. Fortunately, none
+of these issues seem to occur in real-life as far as I can tell, and
+are caused by closing down mgmt at weird times.
+
+* Found a bug (now fixed) in the upstream lexer Yikes! See:
+57ce3fa587897d74634c1216af67dd42252c64e5
+
+* We're looking for help writing Amazon, Google, DigitalOcean, etc
+resources if anyone is interested, reach out to us. Particularly if
+there is support from those organizations as well.
+
+* Many other bug fixes, changes, etc...
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started! For details please see:
+
+https://github.com/purpleidea/mgmt/blob/master/docs/faq.md#how-do-i-con
+tribute-to-the-project-if-i-dont-know-golang
+
+Many new tagged #mgmtlove issues were tagged:
+https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%
+3Amgmtlove
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved. This is fun and friendly! You get to improve your skills,
+and we get some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+Felix Frank, James Shubin, Jonathan Gold, Kevin Kuehler, Michael Lesko-
+Krleza, Tom Payne, Vincent Membré
+We had 7 unique committers since 0.0.16, and have had 56 overall.
+run 'git log 0.0.16..0.0.17' to see what has changed since 0.0.16
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.18

@@ -0,0 +1,106 @@
+I've just released version 0.0.18 of mgmt!
+
+> 202 files changed, 5606 insertions(+), 1880 deletions(-)
+
+There's some great stuff that landed since 0.0.17, including:
+
+* A re-write of the core engine algorithm
+* Tests are very stable
+* At least three old bugs were killed
+* An infra to write tests for individual resources was added
+
+And much more...
+
+This adds a significant amount of polish and bug fixes to mgmt. We're
+on the home stretch to MVP!
+
+DOWNLOAD
+
+Prebuilt binaries are available here:
+https://github.com/purpleidea/mgmt/releases/tag/0.0.18
+
+NEWS
+
+* There was a rare race that would panic the engine on shutdown. This
+only seemed to happen in CPU/system call starved environments like
+travis-ci. This was due to some ignorance when writing this early part
+of the code base. The algorithm has been re-written, and this also
+removed the use of at least one mutex. Things should be stable now, and
+also much faster. (Although perf was never an issue.)
+
+* A hidden race/deadlock in the exec resource was found and killed.
+Woo! Some new tools to help find these and other problems are in misc/
+
+* The early converger code was re-written. I was not as knowledgeable
+about golang in the very beginning, and this code needed refreshing. It
+contained a rare deadlock which needed to be killed.
+
+* Toshaan added an uptime() function.
+
+* Julien added a method for generating some simple functions for the
+language.
+
+* Lander added two new functions.
+
+* James added a new readfile() function, and other examples.
+
+* The template function now allows you to use imported functions. They
+use underscores instead of periods for namespace separation due to a
+limitation in the template library.
+
+* Kevin and I killed a tricky race in the SocketSet code! Woo :) Kevin
+also added a great cpucount() fact!
+
+* James gave a number of presentations at FOSDEM. Some recordings are
+available: https://purpleidea.com/talks/
+
+* We're looking for help writing Amazon, Google, DigitalOcean, etc
+resources if anyone is interested, reach out to us. Particularly if
+there is support from those organizations as well.
+
+* Many other bug fixes, changes, etc...
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+BUGS
+
+* An unfortunate bug in the type unification code was found. This can
+cause small code bases to take a lot of ram/cpu to run. This will be
+prioritized in an upcoming release. Until then you'll have to avoid
+fancy type unification. (Specify types you know when it has to guess.)
+
+If efficient type unification algorithms are your specialty, please let
+us know, we'd like your help!
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started! For details please see:
+
+https://github.com/purpleidea/mgmt/blob/master/docs/faq.md#how-do-i-con
+tribute-to-the-project-if-i-dont-know-golang
+
+Many tagged #mgmtlove issues exist:
+https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%
+3Amgmtlove
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved. This is fun and friendly! You get to improve your skills,
+and we get some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+Felix Frank, James Shubin, Jeff Waugh, Johan Bloemberg, Julien Pivotto,
+Kevin Kuehler, Lander Van den Bulcke, Toshaan Bharvani
+We had 8 unique committers since 0.0.17, and have had 58 overall.
+run 'git log 0.0.17..0.0.18' to see what has changed since 0.0.17
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.19

@@ -0,0 +1,131 @@
+I've just released version 0.0.19 of mgmt!
+
+> 361 files changed, 10451 insertions(+), 3919 deletions(-)
+
+This is a very important (and huge) release and has some important
+fixes that landed since 0.0.18, including:
+
+* A huge re-write of the elastic etcd clustering code base
+* A significant improvement in the type unification algorithm
+* An important import/class scoping bug was discovered and fixed
+* New mcl functions and resource improvements
+
+And much more...
+
+What comes next is just polish, new features and small bug fixes!
+
+DOWNLOAD
+
+Prebuilt binaries are available here:
+https://github.com/purpleidea/mgmt/releases/tag/0.0.19
+
+NEWS
+
+* A giant etcd re-write was completed and merged. The elastic
+clustering algorithm is not perfect, however it should suffice for most
+use cases, and it's always possible to point mgmt at an external etcd
+cluster if you don't understand the limitations of the automatic
+clustering algorithm. The important part is that the core code is much
+cleaner now, so hopefully races and bugs of ignorance are gone now. :)
+
+* I found an unfortunate bug in the type unification algorithm that
+severely impacted performance for some types of code bases. This is now
+fixed, and I hope we should not experience problems again! Special
+thanks to Sam for talking me through the problem and understanding the
+space better! Woo \o/
+
+* An important import/class scoping bug was fixed. Thanks to Nicolas
+for the bug report. We also added tests for this too!
+
+* Nicolas also added our first os detection function. os.is_debian and
+os.is_redhat are now in core. Get your favourite os added today!
+
+* The polymorphic len function can also check str length.
+
+* The exec resource got a big cleanup. It also learned the interrupt
+trait so that long running commands can be forcefully killed if need
+be.
+
+* A fancy new test infra for testing functions over time was added.
+Anytime we want to check our individual FRP functions are working as
+expected, this is an easy way to add a test. This way, if we ever find
+a bug, we can drop in a test with the fix. This actually helped find a
+very subtle bug in readfile that nobody had experienced yet!
+
+* File res with state => exists but no content now performs as
+expected.
+
+* Improved send/recv, since it was neglected a bit. Hopefully it ends
+up being a useful primitive.
+
+* Added a new synchronization primitive that I'm called
+SubscribedSignal. I found it very useful for building some of my code,
+and I hope you'll find it useful too. I'd offer it upstream to the sync
+package if Google didn't force their crappy CLA nonsense on everyone
+who wanted to send a patch. :/ Death by 1000 paper cuts, I guess.
+
+* Added a match function in the new regexp core package. Try it out and
+add some more functions!
+
+* Wouter has been testing mgmt and filling all sorts of useful bug
+reports. We fixed at least one related to a report, and more are
+planned for the next release. Wouter also sent in one cleanup patch to
+remove some dead code. Welcome to the project!
+
+* We're looking for help writing Amazon, Google, DigitalOcean, etc
+resources if anyone is interested, reach out to us. Particularly if
+there is support from those organizations as well.
+
+* Many other bug fixes, changes, etc...
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+BUGS
+
+* There are a few known issues, in particular with some over eager
+checking done in the Validate portion of two resources, that should
+actually be runtime checks in CheckApply. As a result, if you intend to
+change some state during the graph execution, the resource won't see
+it. These should be very easy to fix if someone is interested in
+writing the patch!
+
+TALKS
+
+* James will be presenting at this year's OSDC in Berlin. There will be
+a workshop: https://osdc.de/events/mgmt-config-workshop/
+and a talk:
+https://osdc.de/events/mgmt-config-the-future-of-your-autonomous-datacentre/
+Sign up soon if you want to guarantee a spot, as they're limited!
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started! For details please see:
+
+https://github.com/purpleidea/mgmt/blob/master/docs/faq.md#how-do-i-con
+tribute-to-the-project-if-i-dont-know-golang
+
+Many tagged #mgmtlove issues exist:
+https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%
+3Amgmtlove
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved. This is fun and friendly! You get to improve your skills,
+and we get some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+Adam Sigal, Felix Frank, James Shubin, Jonathan Gold, Michael Schubert,
+Mitch Fossen, Nicolas Charles, Wouter Dullaert
+We had 8 unique committers since 0.0.18, and have had 63 overall.
+run 'git log 0.0.18..0.0.19' to see what has changed since 0.0.18
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.20

@@ -0,0 +1,145 @@
+I've just released version 0.0.20 of mgmt!
+
+> 295 files changed, 8585 insertions(+), 1413 deletions(-)
+
+This was a very challenging release but it includes many useful changes
+since 0.0.19, including:
+
+* Function values / lambdas exist and are first-class
+* Over 70 new tests have been added!
+* Core functions, classes, and globals can now be written in mcl code
+* A new compiler "Ordering" step was added
+
+And much more...
+
+DOWNLOAD
+
+Prebuilt binaries are available here:
+https://github.com/purpleidea/mgmt/releases/tag/0.0.20
+
+NEWS
+
+* After a long and challenging road, I finally got function values and
+lambdas merged. If you find any bugs, please let me know! You can now
+treat functions as first-class values, and even use them as closures by
+capturing variable state.
+
+* Over 70 new tests were added, most of which test the behaviour of the
+new functions.
+
+* Core packages always allowed you to write new functions in pure
+golang, but now you can implement new functions, classes, and even
+variables in native mcl code! It's still desirable and perhaps
+efficient in some cases to want native golang implementations, but all
+good programs self-host some of their stdlib in their own language
+eventually.
+
+* A new compiler step called "Ordering" was added. It's hidden inside
+the SetScope step, but now lets us generate code ordering graphs and
+determine exactly what to run first.
+
+* Light copying of Node's allows more correct and efficient function
+graphs that can share common vertices and edges. For example, if two
+different closures capture a variable $x, they'll both use the same
+copy when running the function, since the compiler can prove if they're
+identical.
+
+* Improved the type system slightly to allow advanced type comparisons.
+
+* The type unification algorithm was improved. Hopefully it should
+solve all scenarios without needing the recursive solver which was very
+slow. If you find a case that isn't speedy, please let us know!
+
+* Added subtest listing by using -short and -v in a test. This lets you
+know what's available and how to run individual sub tests easily.
+
+* Support for the systemd STATE_DIRECTORY and xdg cache dir was added
+by new contributor John! Thanks!
+
+* New contributor Adam added a pgraph test.
+
+* A bug in the systemd mount resource was fixed. Hopefully it should
+work correctly now.
+
+* A bug that prevented us from allowing nested system imports was
+fixed. Nest away! This will pave the way for us to automatically import
+most of the golang standard library by doing: import "golang/regexp" or
+golang/whatever".
+
+* Added an example showing that unicode is allowed in strings.
+
+* Fixed a rare race in the engine.
+
+* Added some new core functions including math.mod and datetime
+improvements.
+
+* Changed the API to remove the use of --lang. This avoids the
+stuttering.
+
+* Moved to golang 1.11 and etcd 3.3.13. The later includes a fix for an
+un-catchable error scenario which we fixed in etcd.
+
+* Improved the pgraph library significantly so that we can generate
+better graphs with accurate vertices based on the vertex pointers.
+
+* Added ArchLinux OS family detection.
+
+* We're looking for help writing Amazon, Google, DigitalOcean, etc
+resources if anyone is interested, reach out to us. Particularly if
+there is support from those organizations as well.
+
+* Many other bug fixes, changes, etc...
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+BUGS
+
+* There are a few known issues with some disabled code paths in the new
+function value code. These issues don't *need* to be fixed, but if they
+are, then we should see a slight performance increase. Happy to have
+someone dig into these, and they shouldn't bother anyone.
+
+* Some of the pre-built binaries might not work on your system. We need
+to start building them with the right dependencies so that `ldd`
+related things are happy. For now, please try building yourself if the
+build doesn't work for you, or help improve our build system.
+
+TALKS
+
+I'll be giving a talk at an upcoming mini-conference in Montreal. If
+you're interested in attending, please let me know.
+If you'd like to give an mgmt talk somewhere, please let me know!
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started! For details please see:
+
+https://github.com/purpleidea/mgmt/blob/master/docs/faq.md#how-do-i-con
+tribute-to-the-project-if-i-dont-know-golang
+
+Many tagged #mgmtlove issues exist:
+https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%
+3Amgmtlove
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved. This is fun and friendly! You get to improve your skills,
+and we get some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+Adam Sigal, Christian Rebischke, Felix Frank, James Shubin, Jan
+Martens, Johan Bloemberg, John Hooks, Ward Vandewege
+We had 8 unique committers since 0.0.19, and have had 67 overall.
+run 'git log 0.0.19..0.0.20' to see what has changed since 0.0.19
+
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.21

@@ -0,0 +1,133 @@
+I've just released version 0.0.21 of mgmt!
+
+> 178 files changed, 4351 insertions(+), 829 deletions(-)
+
+This was a very lonely release but it includes some very useful
+additions since 0.0.20, including:
+
+* The first mgmt meme!
+* Working distro packages for Fedora, Debian, Ubuntu and Arch!
+* Reversible resources!
+* A deploy package to let you read files from the active deploy
+* Improved file resource behaviours
+
+And much more...
+
+DOWNLOAD
+
+Prebuilt binaries are available here:
+https://github.com/purpleidea/mgmt/releases/tag/0.0.21
+
+NEWS
+
+* Someone made a cool mgmt meme. Look in art/mgmt_*_meme.jpg
+
+* Distro packages are now built properly, so they should all work now.
+We have builds for Fedora-30, Fedora-29, Debian-10, Ubuntu-Bionic, and
+Archlinux. If you'd like a build for a different distro/version please
+let me know.
+
+* We finally got rid of the old `Compare(...) bool` API, and moved to
+`Cmp(...) error`. We'll now get more useful information from Res
+compares when they differ. Thanks to new contributor Donald Bakong for
+working on this. He's ramping up his golang contributions, so we expect
+to see more from him in the future!
+
+* We now have reversible resources. Basically if you create a resource
+and specify the reverse metaparam, eg: `Meta:reverse => true`, then if
+a resource is removed (either because a new version of code doesn't
+have it anymore OR more importantly if it was inside an `if` block that
+became false) then the engine will perform some "reverse" action for
+it. For a file, if it was added, we'll remove it. If it was edited,
+we'll undo the edit. If we added ugo+w, we'll remove that. And so on.
+The engine bits are done, and as well so have the file resource bits.
+It should be easy to add this for any other resource where it makes
+sense. This will likely be a very powerful feature that we use a lot.
+
+* The file resource was changed slightly so that by default the "state"
+is undefined. As a result, if you want a file to be created and none is
+present, you need to specify the state. Otherwise specifying "content"
+will only edit a file if it already exists, and otherwise be an error.
+It turns out this is actually a better behaviour, even if it's not
+necessarily intuitive for puppet users. It turns out it simplifies the
+code drastically and makes the reversible file resource much more
+logical. It seems that Puppet and Ansible got this wrong, but Cfengine
+got it right. IIRC. Do you agree? (Look at the code!)
+
+* We now catch CR \r characters in code so that you don't wonder why
+the compiler is telling you about unexpected whitespace. This should
+make your life easier.
+
+* You can now read files from within the deploy. This can be used for
+templates or anything else. This was one of the last missing things
+that was blocking me from writing useful mcl modules.
+
+* Fixed a copy-pasta bug where the != operator (for strings only) was
+actually doing an ==. Woops! The good news is that we've been shaking
+out silly bugs because I've been using mgmt more and more. Hopefully
+there aren't any woops ones like this left!
+
+* A bunch of function, class, and include tests were added. We're
+getting really well tested!
+
+* We're looking for help writing Amazon, Google, DigitalOcean, etc
+resources if anyone is interested, reach out to us. Particularly if
+there is support from those organizations as well.
+
+* Many other bug fixes, changes, etc...
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+BUGS
+
+* Function values as args don't work yet. This is blocking us from
+implementing functions like map/reduce/filter, because they'd want to
+receive a function as input. TBH, I'm a bit tunnel-visioned on this,
+because I'm not the compilers genius that you are. If you can help,
+please let me know. I'll be posting a bunch of test cases that show
+what's needed shortly.
+
+* Three patches have been submitted to mkosi to support the image
+building I've been doing. They're not merged yet, so you'll have to
+apply them yourself if you want to make your own distro images. This
+isn't a major requirement anyone should have, but if they're not
+merged, we'll store them here and apply them as needed.
+
+TALKS
+
+I'll be in Belgium for FOSDEM and CfgMgmtCamp in 2020. If I'm lucky
+I'll have at least one mgmt presentation. I might also consider going
+to DevConf.cz if I get a talk accepted. Feel to ping me if you'd like
+to hack, get consulting, training, etc while I'm in Europe!
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Freenode IRC, or ping this list if
+you'd like help getting started! For details please see:
+
+https://github.com/purpleidea/mgmt/blob/master/docs/faq.md#how-do-i-con
+tribute-to-the-project-if-i-dont-know-golang
+
+Many tagged #mgmtlove issues exist:
+https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%
+3Amgmtlove
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved. This is fun and friendly! You get to improve your skills,
+and we get some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+bjanssens, Donald Bakong, James Shubin
+We had 3 unique committers since 0.0.20, and have had 69 overall.
+run 'git log 0.0.20..0.0.21' to see what has changed since 0.0.20
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.22

@@ -0,0 +1,160 @@
+I've just released version 0.0.22 of mgmt!
+
+> 579 files changed, 17984 insertions(+), 3136 deletions(-)
+
+Compared to the last release, this is a monster. Previously:
+
+> 178 files changed, 4351 insertions(+), 829 deletions(-)
+
+I apologize for not doing a release earlier, but to be quite honest,
+I've been busy, the people who are playing with mgmt are doing their
+own builds anyways, and there are still some unimplemented, pre-
+production features missing.
+
+Also, I started a new job. News on my blog and how (if at all) it
+affects mgmt is there.
+
+This is still an incredibly important release, so let's cover some of
+the points!
+
+* This is the last release before we switch to go.mod
+* IRC channel moved to #mgmtconfig on libera.chat after Freenode died
+* New resources including tftp, dhcp, and http (all as servers, wow!)
+* New string interpolation implementation with many tests
+* Resource fields can accept complex structs and other types now
+* Improved type unification solver and new invariants like generator
+* A new polymorphic function API interface
+
+And much more...
+
+DOWNLOAD
+
+Prebuilt binaries are NOT available here for this release:
+https://github.com/purpleidea/mgmt/releases/tag/0.0.22
+
+NEWS
+
+* The file resource supports building files from other "fragments".
+This is magic and automatic and real-time. Docs and examples are in the
+repo.
+
+* The file resource (and others) have a new trait and queryable API to
+make decisions based on what other resources are in the graph.
+
+* The file resource has a "purge" option to remove unmanaged files from
+a managed directory.
+
+* A lot of built-in functions are auto-generated from the stdlib. Most
+things you would want are now present, particularly if they're pure
+functions.
+
+* There's a new consul KV resource.
+
+* File resources support symbolic modes now!
+
+* New tftp related resources are now present. They're great and I use
+them to provision things!
+
+* A docker image resource was added.
+
+* First-class constants now exist. So you can do
+$const.res.file.state.exists instead of typing "exists" which is prone
+to typos. This is more verbose, but it's safer if that's your priority.
+
+* We found a bug with fuzzing! Cool, thanks Patrick!
+
+* We have dhcp server related resources. This is pretty cool when
+combined with the tftp resource and you can provision a lot of stuff
+from your laptop and one binary now.
+
+* We also have http server resources. Combined with the tftp and dhcp
+resources mgmt starts to look like a powerful tool to greenfield a new
+datacentre and then take over and manage it continuous. All from a
+single, type-safe, code base. Of course you can do other things with
+this, and I'm looking forward to seeing the ideas that I haven't
+thought of yet! PS: An http:ui has been partially implemented too. Ping
+if you want to know more.
+
+* Resource fields couldn't previously accept anonymous structs as types
+because of how golang built its reflect library. Joe found an elegant
+workaround, thanks!
+
+* The type unification solver was improved to support some new
+invariants. This makes a lot of new things possible, and was done to
+support new complex functions including the eventual addition of map,
+reduce, and filter. One of the new invariants is a "generator"
+invariant, so that unification can take into account the entire
+relevant parts of the AST. It's not a textbook CS implementation, but
+it's based on sound theory I think, and it seems to work great. If you
+find an edge case, please let us know.
+
+* The polymorphic function interface was changed to use the new
+unification logic. This makes a lot more sense. All the functions have
+been ported to the new interface.
+
+* 42
+
+* We're looking for help writing Amazon, Google, DigitalOcean, etc
+resources if anyone is interested, reach out to us. Particularly if
+there is support from those organizations as well.
+
+* Many other bug fixes, changes, etc...
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+BUGS
+
+* Function values as args don't work yet. This is blocking us from
+implementing functions like map/reduce/filter, because they'd want to
+receive a function as input. TBH, I'm a bit tunnel-visioned on this,
+because I'm not the compilers genius that you are. If you can help,
+please let me know. I'll be posting a bunch of test cases that show
+what's needed shortly.
+
+(This is the exact message I wrote last time. I've made a lot of
+progress since then, but motivation here has been low. Reach out if you
+can help.)
+
+TALKS
+
+Hopefully CfgMgmtCamp in 2022 will be back on. If we're lucky and safe,
+maybe I can travel there. TBD... Feel to ping me if you'd like to hack,
+talk, whatever if I'm in Europe.
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Libera IRC, or ping this list if
+you'd like help getting started! For details please see:
+
+https://github.com/purpleidea/mgmt/blob/master/docs/faq.md#how-do-i-con
+tribute-to-the-project-if-i-dont-know-golang
+
+Many tagged #mgmtlove issues exist:
+https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%
+3Amgmtlove
+
+Although asking in IRC is the best way to find something to work on.
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved. This is fun and friendly! You get to improve your skills,
+and we get some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+Adam Sigal, Ahmed Al-Hulaibi, David Randall, Derek Buckley, Donald
+Bakong, Felix Frank, Francois Rompre-Lanctot, Ivan Pejić, James Shubin,
+Jean-Philippe Evrard, Jimmy Tang, Joe Groocock, Jonathan Gold, Julien
+Pivotto, Kenneth Hoste, Matthew Lesko-Krleza, Patrick Meyer, viq, Yohan
+Belval
+We had 19 unique committers since 0.0.21, and have had 82 overall.
+run 'git log 0.0.21..0.0.22' to see what has changed since 0.0.21
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.23

@@ -0,0 +1,102 @@
+I've just released version 0.0.23 of mgmt!
+
+>  424 files changed, 7051 insertions(+), 2256 deletions(-)
+
+This is a fairly quiet release, and I'm mostly doing this to have a
+permanent tag before I start really breaking git master.
+
+I'd like to apologize for things being kind of quiet. I've had to focus
+on life and making money to pay my bills, and I've been struggling a
+bit to complete some of the tougher algorithmic parts that I think are
+necessary for a solid MVP. Hopefully I will succeed, but to do so, it's
+going to be easier if I break git master and then sort things out
+later.
+
+I'm feeling optimistic about the future, although help with some
+complex concurrent programming would certainly be appreciated.
+
+With that, here are a few highlights from the release:
+
+* We're using go.mod, but I'm not keeping it up-to-date regularly yet.
+
+* We have an os.system(`cmd`) function!
+
+* We replaced go-bindata with the embed package.
+
+* We added a hetzner vm resource.
+
+* We did a giant lang/ package refactor.
+
+* Printf supports %v now (any type).
+
+And much more...
+
+DOWNLOAD
+
+Prebuilt binaries are NOT available here for this release:
+https://github.com/purpleidea/mgmt/releases/tag/0.0.23
+
+NEWS
+
+* We have our Libera IRC channel bridged to Matrix, so you can join
+that way too.
+
+* We're looking for help writing Amazon, Google, DigitalOcean, Hetzner,
+etc, resources if anyone is interested, reach out to us. Particularly
+if there is support from those organizations as well.
+
+* Many other bug fixes, changes, etc...
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+BUGS
+
+* Function values as args don't work yet. This is blocking us from
+implementing functions like map/reduce/filter, because they'd want to
+receive a function as input.
+
+(This is the exact message I wrote last time. I've made a lot of
+progress since then, but motivation here has been low. Reach out if you
+can help.)
+
+TALKS
+
+I don't have anything planned until CfgMgmtCamp 2024. If you'd like to
+book me for a private event, or sponsor my travel for your conference,
+please let me know.
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Libera IRC or Matrix, or ping this
+list if you'd like help getting started! For details please see:
+
+https://github.com/purpleidea/mgmt/blob/master/docs/faq.md#how-do-i-con
+tribute-to-the-project-if-i-dont-know-golang
+
+Many tagged #mgmtlove issues exist:
+https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%
+3Amgmtlove
+
+Although asking in IRC is the best way to find something to work on.
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved. This is fun and friendly! You get to improve your skills,
+and we get some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+dantefromhell, James Shubin, Jef Masereel, Joe Groocock, Samuel
+Gélineau
+We had 5 unique committers since 0.0.22, and have had 85 overall.
+run 'git log 0.0.22..0.0.23' to see what has changed since 0.0.22
+
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.24

@@ -0,0 +1,161 @@
+I've just released version 0.0.24 of mgmt!
+
+
+> 600 files changed, 13622 insertions(+), 6907 deletions(-)
+
+This is a huge and hugely important release! It has been a long time
+coming. We have lambdas! I could not have done this without the
+unrelentingly supportive and brilliant Samuel Gélineau.
+
+Getting past the blockers and tricky code changes was all thanks to
+him. Cleanups, polish and making it more golang idiomatic was my doing.
+(The easy stuff.) If Sam wanted to be a golang expert, he could have
+done it all, but it was more sensible than I do all the mundane and
+filler stuff.
+
+With that, here are a few highlights from the release:
+
+* We have working lambdas, including iter.map =D
+
+* We have a new function engine!
+
+* We have improved type unification!
+
+* We have an improved resource engine!
+
+* We have improved many of the internal API's.
+
+* We have so many tests.
+
+And much more...
+
+DOWNLOAD
+
+Prebuilt binaries are NOT available here for this release:
+https://github.com/purpleidea/mgmt/releases/tag/0.0.24
+
+NEWS
+
+* Our main tests are now in the excellent .txtar format. This makes
+things much easier to manage.
+
+* The iter.map function can be named as such due to parser tricks! No
+need to name it xmap anymore!
+
+* The unification solver has been greatly improved. We can infer a lot
+more about function types.
+
+* The resources API uses the context package for closing Watch and
+returning early from CheckApply. The next step would be to remove all
+the resource-specific timeout code and make that a metaparam.
+
+* A new sync primitive has been added in case you'd like to use it
+somewhere. We'd love help adding an even more complex one. Look in
+util/sync.go for more information.
+
+* Sam added some beautiful type inference debugging that makes things
+easier for those familiar with the standard literature.
+
+* An important bug in standalone etcd has been fixed. While embedded
+etcd and automatic clustering isn't "supported" (it's buggy) the
+status-quo of using your own etcd cluster is stable, and you can even
+use the embedded etcd server in standalone mode...
+
+* This means you can run `mgmt etcd` and get the standard etcd binary
+behviour that you'd get from running `etcd` normally. This makes it
+easy to use both together since you only need to transport one binary
+around. (And maybe mgmt will do that for you!)
+
+* I fixed and cleaned up some sketchy code in the resource engine. I
+had been unmotivated to fix this for a while because I really wanted
+lambdas first, but now that they are in, I took a good look at the
+code, made some fixes, and I'm really happy with it now.
+
+* Metaparams are appropriately stateful between graph switches now.
+Retry is the easy example. Limit/Burst need to be ported if you care
+about these fine details.
+
+* A RetryReset metaparam has been added. This is another good example
+of how powerful metaparams are and how much potential there is for
+building systems with these and future ones.
+
+* A bunch of internal API's have been updated. This makes it better for
+function and resource writers! Some GAPI changes also got pushed
+through that make things clearer for those reading code.
+
+* We have a listlookup function. It's still missing syntactic sugar
+though!
+
+* Our new function graph engine is called "dage". I think it's pretty
+clever. There's a chance there is still a bug inside, but it's unclear.
+Please report any issues. If you have some large machines I can test
+very large and fast graphs on, please let me know.
+
+* Lambdas really work now! The txn and ref/gc code is pretty fantastic.
+
+* Many bugs have been killed!
+
+* We're looking for help writing Amazon, Google, DigitalOcean, Hetzner,
+etc, resources if anyone is interested, reach out to us. Particularly
+if there is support from those organizations as well.
+
+* Many other bug fixes, changes, etc...
+
+* See the git log for more NEWS, and for anything notable I left out!
+
+BUGS/TODO
+
+* Function values getting _passed_ to resources doesn't work yet, but
+it's not a blocker, but it would definitely be useful. We're looking
+into it.
+
+* Function graphs are unnecessarily dynamic. We might make them more
+static so that we don't need as many transactions. This is really a
+compiler optimization and not a bug, but it's something important we'd
+like to have.
+
+* Running two Txn's during the same pause would be really helpful. I'm
+not sure how much of a performance improvement we'd get from this, but
+it would sure be interesting to build. If you want to build a fancy
+synchronization primitive, then let us know! Again this is not a bug.
+
+TALKS
+
+I don't have anything planned until CfgMgmtCamp 2024. If you'd like to
+book me for a private event, or sponsor my travel for your conference,
+please let me know.
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium
+and hard issues available! You're also welcome to suggest your own!
+Please join us in #mgmtconfig on Libera IRC or Matrix, or ping this
+list if you'd like help getting started! For details please see:
+
+https://github.com/purpleidea/mgmt/blob/master/docs/faq.md#how-do-i-con
+tribute-to-the-project-if-i-dont-know-golang
+
+Many tagged #mgmtlove issues exist:
+https://github.com/purpleidea/mgmt/issues?q=is%3Aissue+is%3Aopen+label%
+3Amgmtlove
+
+Although asking in IRC/matrix is the best way to find something to work
+on.
+
+MENTORING
+
+We offer mentoring for new golang/mgmt hackers who want to get
+involved. This is fun and friendly! You get to improve your skills,
+and we get some patches in return. Ping me off-list for details.
+
+THANKS
+
+Thanks (alphabetically) to everyone who contributed to the latest
+release:
+James Shubin, Kaushal, Laurent Indermuehle, Ofek Atar, Samuel Gélineau
+We had 5 unique committers since 0.0.23, and have had 88 overall.
+run 'git log 0.0.23..0.0.24' to see what has changed since 0.0.23
+
+Happy hacking,
+James
+@purpleidea

docs/release-notes/0.0.9

@@ -0,0 +1,71 @@
+I've just released 0.0.9!
+
+Release tags are now signed with my GPG key.
+
+From now on, I'm going to try and write a release email to the list
+with information about each release. Here we go!
+
+NEWS
+
+* There were far more commits that went into this release than I was
+expecting. I delayed a while because of some nasty races and deadlocks
+I encountered when cleaning some cruft out of the engine.
+
+134 files changed, 5394 insertions(+), 2168 deletions(-)
+
+* We grew initial integration with Prometheus thanks to new contributor
+`roidelapluie`.
+
+* The file resource can now chown/chmod files! Thanks to new
+contributor `mildred`.
+
+* The virt resource can now hotplug/hotunplug cpus. This made for some
+dope demos at CfgMgmtCamp. Special thanks to pkrempa for helping me
+with the libvirt API.
+
+* Native testing of all the golang code is now enabled again. I broke
+this when I split mgmt up into multiple packages. (Sorry!) Golang tests
+in foo_test.go should now run and be tested automatically. I'd
+especially like it if someone wrote some for pgraph/pgraph.go:
+GraphSync().
+
+* Documentation has been significantly improved. We have a resource
+guide (for writing new native resources) and much more. We also now
+build the docs as a RTD project:
+https://mgmt.readthedocs.io/en/master/
+Patches welcome to make it style as pretty as GitHub markdown does.
+
+* See the git log for more NEWS, and sorry for anything notable I left
+out!
+
+BUGS
+
+* I hope to resolve this soon, but it shouldn't block further
+development on git master for now. The issue: if you make extremely
+high speed graph changes to graphs involving the virt resource, it can
+eventually cause a panic. This is being tracked here:
+https://github.com/libvirt/libvirt-go/issues/7 (help welcome!)
+
+GLUSTERFS
+
+I've started working on some stuff for Glusterd so that it can embed
+mgmt as a lib, and use the resource model to simplify cluster
+management. This will involve writing Gluster resources in mgmt
+(volume, brick, etc...) and all sorts of other fun stuff. If you'd like
+to participate, please LMK!
+
+MISC
+
+We're still looking for new contributors, and there are easy, medium and hard issues available! You're also welcome to suggest your own! Please join us in #mgmtconfig on Freenode IRC, or ping this list if you'd like help getting started!
+
+THANKS
+
+We had 12 unique committers since 0.0.8, and have had 29 overall.
+Thanks (alphabetically) to everyone who contributed to the latest
+release: Daniele Sluijters, Daniel P. Berrange, Felix Frank, goberghen,
+James Shubin, Julien Pivotto, Kaushal M, Lars Kulseng, Mildred Ki'Lya,
+Sean Jones, Steve Milner, Tom Ritserveldt.
+
+Happy hacking,
+James
+@purpleidea

docs/resource-guide.md

@@ -0,0 +1,793 @@
+# Resource guide
+
+## Overview
+
+The `mgmt` tool has built-in resource primitives which make up the building
+blocks of any configuration. Each instance of a resource is mapped to a single
+vertex in the resource [graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph).
+This guide is meant to instruct developers on how to write a brand new resource.
+Since `mgmt` and the core resources are written in golang, some prior golang
+knowledge is assumed.
+
+## Theory
+
+Resources in `mgmt` are similar to resources in other systems in that they are
+[idempotent](https://en.wikipedia.org/wiki/Idempotence). Our resources are
+uniquely different in that they can detect when their state has changed, and as
+a result can run to revert or repair this change instantly. For some background
+on this design, please read the
+[original article](https://purpleidea.com/blog/2016/01/18/next-generation-configuration-mgmt/)
+on the subject.
+
+## Resource Prerequisites
+
+### Imports
+
+You'll need to import a few packages to make writing your resource easier. Here
+is the list:
+
+```
+	"github.com/purpleidea/mgmt/engine"
+	"github.com/purpleidea/mgmt/engine/traits"
+```
+
+The `engine` package contains most of the interfaces and helper functions that
+you'll need to use. The `traits` package contains some base functionality which
+you can use to easily add functionality to your resource without needing to
+implement it from scratch.
+
+### Resource struct
+
+Each resource will implement methods as pointer receivers on a resource struct.
+The naming convention for resources is that they end with a `Res` suffix.
+
+The resource struct should include an anonymous reference to the `Base` trait.
+Other `traits` can be added to the resource to add additional functionality.
+They are discussed below.
+
+You'll most likely want to store a reference to the `*Init` struct type as
+defined by the engine. This is data that the engine will provide to your
+resource on Init.
+
+Lastly you should define the public fields that make up your resource API, as
+well as any private fields that you might want to use throughout your resource.
+Do _not_ depend on global variables, since multiple copies of your resource
+could get instantiated.
+
+You'll want to add struct tags based on the different frontends that you want
+your resources to be able to use. Some frontends can infer this information if
+it is not specified, but others cannot, and some might poorly infer if the
+struct name is ambiguous.
+
+If you'd like your resource to be accessible by the `YAML` graph API (GAPI),
+then you'll need to include the appropriate YAML fields as shown below.
+
+#### Example
+
+```golang
+type FooRes struct {
+	traits.Base // add the base methods without re-implementation
+	traits.Groupable
+	traits.Refreshable
+
+	init *engine.Init
+
+	Whatever string `lang:"whatever" yaml:"whatever"` // you pick!
+	Baz      bool   `lang:"baz" yaml:"baz"`           // something else
+
+	something string // some private field
+}
+```
+
+## Resource API
+
+To implement a resource in `mgmt` it must satisfy the
+[`Res`](https://github.com/purpleidea/mgmt/blob/master/engine/resources.go)
+interface. What follows are each of the method signatures and a description of
+each.
+
+### Default
+
+```golang
+Default() engine.Res
+```
+
+This returns a populated resource struct as a `Res`. It shouldn't populate any
+values which already get a good default as the respective golang zero value. In
+general it is preferable if the zero values make for the correct defaults.
+(This is to say, resources are designed to behave safely and intuitively
+when parameters take a zero value, whenever this is possible.)
+
+#### Example
+
+```golang
+// Default returns some sensible defaults for this resource.
+func (obj *FooRes) Default() engine.Res {
+	return &FooRes{
+		Answer: 42, // sometimes, defaults shouldn't be the zero value
+	}
+}
+```
+
+### Validate
+
+```golang
+Validate() error
+```
+
+This method is used to validate if the populated resource struct is a valid
+representation of the resource kind. If it does not conform to the resource
+specifications, it should return an error. If you notice that this method is
+quite large, it might be an indication that you should reconsider the parameter
+list and interface to this resource. This method is called by the engine
+_before_ `Init`. It can also be called occasionally after a Send/Recv operation
+to verify that the newly populated parameters are valid. Remember not to expect
+access to the outside world when using this.
+
+#### Example
+
+```golang
+// Validate reports any problems with the struct definition.
+func (obj *FooRes) Validate() error {
+	if obj.Answer != 42 { // validate whatever you want
+		return fmt.Errorf("expected an answer of 42")
+	}
+	return nil
+}
+```
+
+### Init
+
+```golang
+Init() error
+```
+
+This is called to initialize the resource. If something goes wrong, it should
+return an error. It should do any resource specific work such as initializing
+channels, sync primitives, or anything else that is relevant to your resource.
+If it is not need throughout, it might be preferable to do some initialization
+and tear down locally in either the Watch method or CheckApply method. The
+choice depends on your particular resource and making the best decision requires
+some experience with mgmt. If you are unsure, feel free to ask an existing
+`mgmt` contributor. During `Init`, the engine will pass your resource a struct
+containing some useful data and pointers. You should save a copy of this pointer
+since you will need to use it in other parts of your resource.
+
+#### Example
+
+```golang
+// Init initializes the Foo resource.
+func (obj *FooRes) Init(init *engine.Init) error
+	obj.init = init // save for later
+
+	// run the resource specific initialization, and error if anything fails
+	if some_error {
+		return err // something went wrong!
+	}
+	return nil
+}
+```
+
+This method is always called after `Validate` has run successfully, with the
+exception that we can't prevent a malicious or buggy `libmgmt` user to not run
+this. In other words, you should expect `Validate` to have run first, but you
+shouldn't allow `Init` to dangerously `rm -rf /$the_world` if your code only
+checks `$the_world` in `Validate`. Remember to always program safely!
+
+### Cleanup
+
+```golang
+Cleanup() error
+```
+
+This is called to cleanup after the resource. It is usually not necessary, but
+can be useful if you'd like to properly close a persistent connection that you
+opened in the `Init` method and were using throughout the resource. It is *not*
+the shutdown signal that tells the resource to exit. That happens in the Watch
+loop.
+
+#### Example
+
+```golang
+// Cleanup is run by the engine to clean up after the resource is done.
+func (obj *FooRes) Cleanup() error {
+	err := obj.conn.Close() // close some internal connection
+	obj.someMap = nil       // free up some large data structure from memory
+	return err
+}
+```
+
+You should probably check the return errors of your internal methods, and pass
+on an error if something went wrong.
+
+### CheckApply
+
+```golang
+CheckApply(ctx context.Context, apply bool) (checkOK bool, err error)
+```
+
+`CheckApply` is where the real _work_ is done. Under normal circumstances, this
+function should check if the state of this resource is correct, and if so, it
+should return: `(true, nil)`. If the `apply` variable is set to `true`, then
+this means that we should then proceed to run the changes required to bring the
+resource into the correct state. If the `apply` variable is set to `false`, then
+the resource is operating in _noop_ mode and _no operational changes_ should be
+made! The ctx should be monitored in case a shutdown has been requested. This
+may be used if a timeout occurred, or if the user shutdown the engine.
+
+After having executed the necessary operations to bring the resource back into
+the desired state, or after having detected that the state was incorrect, but
+that changes can't be made because `apply` is `false`, you should then return
+`(false, nil)`.
+
+You must cause the resource to converge during a single execution of this
+function. If you cannot, then you must return an error! The exception to this
+rule is that if an external force changes the state of the resource while it is
+being remedied, it is possible to return from this function even though the
+resource isn't now converged. This is not a bug, as the resources `Watch`
+facility will detect the new change, ultimately resulting in a subsequent call
+to `CheckApply`.
+
+#### Example
+
+```golang
+// CheckApply does the idempotent work of checking and applying resource state.
+func (obj *FooRes) CheckApply(ctx context.Context, apply bool) (bool, error) {
+	// check the state
+	if state_is_okay { return true, nil } // done early! :)
+
+	// state was bad
+
+	if !apply { return false, nil } // don't apply, we're in noop mode
+
+	if any_error { return false, err } // anytime there's an err!
+
+	// do the apply!
+	return false, nil // after success applying
+}
+```
+
+The `CheckApply` function is called by the `mgmt` engine when it believes a call
+is necessary. Under certain conditions when a `Watch` call does not invalidate
+the state of the resource, and no refresh call was sent, its execution might be
+skipped. This is an engine optimization, and not a bug. It is mentioned here in
+the documentation in case you are confused as to why a debug message you've
+added to the code isn't always printed.
+
+#### Paired execution
+
+For many resources it is not uncommon to see `CheckApply` run twice in rapid
+succession. This is usually not a pathological occurrence, but rather a healthy
+pattern which is a consequence of the event system. When the state of the
+resource is incorrect, `CheckApply` will run to remedy the state. In response to
+having just changed the state, it is usually the case that this repair will
+trigger the `Watch` code! In response, a second `CheckApply` is triggered, which
+will likely find the state to now be correct.
+
+#### Summary
+
+* Anytime an error occurs during `CheckApply`, you should return `(false, err)`.
+* If the state is correct and no changes are needed, return `(true, nil)`.
+* You should only make changes to the system if `apply` is set to `true`.
+* After checking the state and possibly applying the fix, return `(false, nil)`.
+* Returning `(true, err)` is a programming error and can have a negative effect.
+
+### Watch
+
+```golang
+Watch(ctx context.Context) error
+```
+
+`Watch` is a main loop that runs and sends messages when it detects that the
+state of the resource might have changed. To send a message you should write to
+the input event channel using the `Event` helper method. The Watch function
+should run continuously until a shutdown message is received. If at any time
+something goes wrong, you should return an error, and the `mgmt` engine will
+handle possibly restarting the main loop based on the `retry` meta parameter.
+
+It is better to send an event notification which turns out to be spurious, than
+to miss a possible event. Resources which can miss events are incorrect and need
+to be re-engineered so that this isn't the case. If you have an idea for a
+resource which would fit this criteria, but you can't find a solution, please
+contact the `mgmt` maintainers so that this problem can be investigated and a
+possible system level engineering fix can be found.
+
+You may have trouble deciding how much resource state checking should happen in
+the `Watch` loop versus deferring it all to the `CheckApply` method. You may
+want to put some simple fast path checking in `Watch` to avoid generating
+obviously spurious events, but in general it's best to keep the `Watch` method
+as simple as possible. Contact the `mgmt` maintainers if you're not sure.
+
+If the resource is activated in `polling` mode, the `Watch` method will not get
+executed. As a result, the resource must still work even if the main loop is not
+running.
+
+You must make sure to cleanup any running code or goroutines before Watch exits.
+
+#### Select
+
+The lifetime of most resources `Watch` method should be spent in an infinite
+loop that is bounded by a `select` call. The `select` call is the point where
+our method hands back control to the engine (and the kernel) so that we can
+sleep until something of interest wakes us up. In this loop we must wait until
+we get a shutdown event from the engine via the `<-ctx.Done()` channel, which
+closes when we'd like to shut everything down. At this point you should cleanup,
+and let `Watch` close.
+
+#### Events
+
+If the `<-ctx.Done()` channel closes, we should shutdown our resource. When we
+want to send an event, we use the `Event` helper function. This automatically
+marks the resource state as `dirty`. If you're unsure, it's not harmful to send
+the event. This will ultimately cause `CheckApply` to run. This method can block
+if the resource is being paused.
+
+#### Startup
+
+Once the `Watch` function has finished starting up successfully, it is important
+to generate one event to notify the `mgmt` engine that we're now listening
+successfully, so that it can run an initial `CheckApply` to ensure we're safely
+tracking a healthy state and that we didn't miss anything when `Watch` was down
+or from before `mgmt` was running. You must do this by calling the
+`obj.init.Running` method.
+
+#### Converged
+
+The engine might be asked to shutdown when the entire state of the system has
+not seen any changes for some duration of time. The engine can determine this
+automatically, but each resource can block this if it is absolutely necessary.
+If you need this functionality, please contact one of the maintainers and ask
+about adding this feature and improving these docs right here.
+
+This particular facility is most likely not required for most resources. It may
+prove to be useful if a resource wants to start off a long operation, but avoid
+sending out erroneous `Event` messages to keep things alive until it finishes.
+
+#### Example
+
+```golang
+// Watch is the listener and main loop for this resource.
+func (obj *FooRes) Watch(ctx context.Context) error {
+	// setup the Foo resource
+	var err error
+	if err, obj.foo = OpenFoo(); err != nil {
+		return err // we couldn't startup
+	}
+	defer obj.whatever.CloseFoo() // shutdown our Foo
+
+	// notify engine that we're running
+	obj.init.Running() // when started, notify engine that we're running
+
+	var send = false // send event?
+	for {
+		select {
+		// the actual events!
+		case event := <-obj.foo.Events:
+			if is_an_event {
+				send = true
+			}
+
+		// event errors
+		case err := <-obj.foo.Errors:
+			return err // will cause a retry or permanent failure
+
+		case <-ctx.Done(): // signal for shutdown request
+			return nil
+		}
+
+		// do all our event sending all together to avoid duplicate msgs
+		if send {
+			send = false
+			obj.init.Event()
+		}
+	}
+}
+```
+
+#### Summary
+
+* Remember to call `Running` when the `Watch` is running successfully.
+* Remember to process internal events and shutdown promptly if asked to.
+* Ensure the design of your resource is well thought out.
+* Have a look at the existing resources for a rough idea of how this all works.
+
+### Cmp
+
+```golang
+Cmp(engine.Res) error
+```
+
+Each resource must have a `Cmp` method. It is an abbreviation for `Compare`. It
+takes as input another resource and must return whether they are identical or
+not. This is used for identifying if an existing resource can be used in place
+of a new one with a similar set of parameters. In particular, when switching
+from one graph to a new (possibly identical) graph, this avoids recomputing the
+state for resources which don't change or that are sufficiently similar that
+they don't need to be swapped out.
+
+In general if all the resource properties are identical, then they usually don't
+need to be changed. On occasion, not all of them need to be compared, in
+particular if they store some generated state, or if they aren't significant in
+some way.
+
+If the resource is identical, then you should return `nil`. If it is not, then
+you should return a short error message which gives the reason it differs.
+
+#### Example
+
+```golang
+// Cmp compares two resources and returns if they are equivalent.
+func (obj *FooRes) Cmp(r engine.Res) error {
+	// we can only compare FooRes to others of the same resource kind
+	res, ok := r.(*FooRes)
+	if !ok {
+		return fmt.Errorf("not a %s", obj.Kind())
+	}
+
+	if obj.Whatever != res.Whatever {
+		return fmt.Errorf("the Whatever param differs")
+	}
+	if obj.Flag != res.Flag {
+		return fmt.Errorf("the Flag param differs")
+	}
+
+	return nil // they must match!
+}
+```
+
+## Traits
+
+Resources can have different `traits`, which means they can be extended to have
+additional functionality or special properties. Those special properties are
+usually added by extending your resource so that it is compatible with
+additional interface that contain the `Res` interface. Each of these interfaces
+represents the additional functionality. Since in most cases this requires some
+common boilerplate, you can usually get some or most of the functionality by
+embedding the correct trait struct anonymously in your struct. This is shown in
+the struct example above. You'll always want to include the `Base` trait in all
+resources. This provides some basics which you'll always need.
+
+What follows are a list of available traits.
+
+### Refreshable
+
+Some resources may choose to support receiving refresh notifications. In general
+these should be avoided if possible, but nevertheless, they do make sense in
+certain situations. Resources that support these need to verify if one was sent
+during the CheckApply phase of execution. This is accomplished by calling the
+`obj.init.Refresh() bool` method, and inspecting the return value. This is only
+necessary if you plan to perform a refresh action. Refresh actions should still
+respect the `apply` variable, and no system changes should be made if it is
+`false`. Refresh notifications are generated by any resource when an action is
+applied by that resource and are transmitted through graph edges which have
+enabled their propagation. Resources that currently perform some refresh action
+include `svc`, `timer`, and `password`.
+
+It is very important that you include the `traits.Refreshable` struct in your
+resource. If you do not include this, then calling `obj.init.Refresh` may
+trigger a panic. This is programmer error.
+
+### Edgeable
+
+Edgeable is a trait that allows your resource to automatically connect itself to
+other resources that use this trait to add edge dependencies between the two. An
+older blog post on this topic is
+[available](https://purpleidea.com/blog/2016/03/14/automatic-edges-in-mgmt/).
+
+After you've included this trait, you'll need to implement two methods on your
+resource.
+
+#### UIDs
+
+```golang
+UIDs() []engine.ResUID
+```
+
+The `UIDs` method returns a list of `ResUID` interfaces that represent the
+particular resource uniquely. This is used with the AutoEdges API to determine
+if another resource can match a dependency to this one.
+
+#### AutoEdges
+
+```golang
+AutoEdges() (engine.AutoEdge, error)
+```
+
+This returns a struct that implements the `AutoEdge` interface. This struct
+is used to match other resources that might be relevant dependencies for this
+resource.
+
+### Groupable
+
+Groupable is a trait that can allow your resource automatically group itself to
+other resources. Doing so can reduce the resource or runtime burden on the
+engine, and improve performance in some scenarios. An older blog post on this
+topic is
+[available](https://purpleidea.com/blog/2016/03/30/automatic-grouping-in-mgmt/).
+
+### Sendable
+
+Sendable is a trait that allows your resource to send values through the graph
+edges to another resource. These values are produced during `CheckApply`. They
+can be sent to any resource that has an appropriate parameter and that has the
+`Recvable` trait. You can read more about this in the Send/Recv section below.
+
+### Recvable
+
+Recvable is a trait that allows your resource to receive values through the
+graph edges from another resource. These values are consumed during the
+`CheckApply` phase, and can be detected there as well. They can be received from
+any resource that has an appropriate value and that has the `Sendable` trait.
+You can read more about this in the Send/Recv section below.
+
+### Collectable
+
+This is currently a stub and will be updated once the DSL is further along.
+
+## Resource Initialization
+
+During the resource initialization in `Init`, the engine will pass in a struct
+containing a bunch of data and methods. What follows is a description of each
+one and how it is used.
+
+### Program
+
+Program is a string containing the name of the program. Very few resources need
+this.
+
+### Hostname
+
+Hostname is the uuid for the host. It will be occasionally useful in some
+resources. It is preferable if you can avoid depending on this. It is possible
+that in the future this will be a channel which changes if the local hostname
+changes.
+
+### Running
+
+Running must be called after your watches are all started and ready. It is only
+called from within `Watch`. It is used to notify the engine that you're now
+ready to detect changes.
+
+### Event
+
+Event sends an event notifying the engine of a possible state change. It is
+only called from within `Watch`.
+
+### Refresh
+
+Refresh returns whether the resource received a notification. This flag can be
+used to tell a `svc` to reload, or to perform some state change that wouldn't
+otherwise be noticed by inspection alone. You must implement the `Refreshable`
+trait for this to work. It is only called from within `CheckApply`.
+
+### Send
+
+Send exposes some variables you wish to send via the `Send/Recv` mechanism. You
+must implement the `Sendable` trait for this to work. It is only called from
+within `CheckApply`.
+
+### Recv
+
+Recv provides a map of variables which were sent to this resource via the
+`Send/Recv` mechanism. You must implement the `Recvable` trait for this to work.
+It is only called from within `CheckApply`.
+
+### World
+
+World provides a connection to the outside world. This is most often used for
+communicating with the distributed database. It can be used in `Init`,
+`CheckApply` and `Watch`. Use with discretion and understanding of the internals
+if needed in `Cleanup`.
+
+### VarDir
+
+VarDir is a facility for local storage. It is used to return a path to a
+directory which may be used for temporary storage. It should be cleaned up on
+resource `Cleanup` if the resource would like to delete the contents. The
+resource should not assume that the initial directory is empty, and it should be
+cleaned on `Init` if that is a requirement.
+
+### Debug
+
+Debug signals whether we are running in debugging mode. In this case, we might
+want to log additional messages.
+
+### Logf
+
+Logf is a logging facility which will correctly namespace any messages which you
+wish to pass on. You should use this instead of the log package directly for
+production quality resources.
+
+## Further considerations
+
+There is some additional information that any resource writer will need to know.
+Each issue is listed separately below!
+
+### Resource registration
+
+All resources must be registered with the engine so that they can be found. This
+also ensures they can be encoded and decoded. Make sure to include the following
+code snippet for this to work.
+
+```golang
+func init() { // special golang method that runs once
+	// set your resource kind and struct here (the kind must be lower case)
+	engine.RegisterResource("foo", func() engine.Res { return &FooRes{} })
+}
+```
+
+### YAML Unmarshalling
+
+To support YAML unmarshalling for your resource, you must implement an
+additional method. It is recommended if you want to use your resource with the
+`yaml` compiler.
+
+```golang
+UnmarshalYAML(unmarshal func(interface{}) error) error // optional
+```
+
+This is optional, but recommended for any resource that will have a YAML
+accessible struct. It is not required because to do so would mean that
+third-party or custom resources (such as those someone writes to use with
+`libmgmt`) would have to implement this needlessly.
+
+The signature intentionally matches what is required to satisfy the `go-yaml`
+[Unmarshaler](https://godoc.org/gopkg.in/yaml.v2#Unmarshaler) interface.
+
+#### Example
+
+```golang
+// UnmarshalYAML is the custom unmarshal handler for this struct. It is
+// primarily useful for setting the defaults.
+func (obj *FooRes) UnmarshalYAML(unmarshal func(interface{}) error) error {
+	type rawRes FooRes // indirection to avoid infinite recursion
+
+	def := obj.Default()     // get the default
+	res, ok := def.(*FooRes) // put in the right format
+	if !ok {
+		return fmt.Errorf("could not convert to FooRes")
+	}
+	raw := rawRes(*res) // convert; the defaults go here
+
+	if err := unmarshal(&raw); err != nil {
+		return err
+	}
+
+	*obj = FooRes(raw) // restore from indirection with type conversion!
+	return nil
+}
+```
+
+## Send/Recv
+
+In `mgmt` there is a novel concept called _Send/Recv_. For some background,
+please read the [introductory article](https://purpleidea.com/blog/2016/12/07/sendrecv-in-mgmt/).
+When using this feature, the engine will automatically send the user specified
+value to the intended destination without requiring much resource specific code.
+Any time that one of the destination values is changed, the engine automatically
+marks the resource state as `dirty`. To detect if a particular value was
+received, and if it changed (during this invocation of `CheckApply`) from the
+previous value, you can query the `obj.init.Recv()` method. It will contain a
+`map` of all the keys which can be received on, and the value has a `Changed`
+property which will indicate whether the value was updated on this particular
+`CheckApply` invocation. The type of the sending key must match that of the
+receiving one. This can _only_ be done inside of the `CheckApply` function!
+
+```golang
+// inside CheckApply, probably near the top
+if val, exists := obj.init.Recv()["some_key"]; exists {
+	obj.init.Logf("the some_key param was sent to us from: %s.%s", val.Res, val.Key)
+	if val.Changed {
+		obj.init.Logf("the some_key param was just updated!")
+		// you may want to invalidate some local cache
+	}
+}
+```
+
+The specifics of resource sending are not currently documented. Please send a
+patch here!
+
+## Composite resources
+
+Composite resources are resources which embed one or more existing resources.
+This is useful to prevent code duplication in higher level resource scenarios.
+The best example of this technique can be seen in the `nspawn` resource which
+can be seen to partially embed a `svc` resource, but without its `Watch`.
+Unfortunately no further documentation about this subject has been written. To
+expand this section, please send a patch! Please contact us if you'd like to
+work on a resource that uses this feature, or to add it to an existing one!
+
+## Frequently asked questions
+
+(Send your questions as a patch to this FAQ! I'll review it, merge it, and
+respond by commit with the answer.)
+
+### Can I write resources in a different language?
+
+Currently `golang` is the only supported language for built-in resources. We
+might consider allowing external resources to be imported in the future. This
+will likely require a language that can expose a C-like API, such as `python` or
+`ruby`. Custom `golang` resources are already possible when using mgmt as a lib.
+Higher level resource collections will be possible once the `mgmt` DSL is ready.
+
+### Why does the resource API have `CheckApply` instead of two separate methods?
+
+In an early version we actually had both "parts" as separate methods, namely:
+`StateOK` (Check) and `Apply`, but the [decision](58f41eddd9c06b183f889f15d7c97af81b0331cc)
+was made to merge the two into a single method. There are two reasons for this:
+
+1. Many situations would involve the engine running both `Check` and `Apply`. If
+the resource needed to share some state (for efficiency purposes) between the
+two calls, this is much more difficult. A common example is that a resource
+might want to open a connection to `dbus` or `http` to do resource state testing
+and applying. If the methods are combined, there's no need to open and close
+them twice. A counter argument might be that you could open the connection in
+`Init`, and close it in `Cleanup`, however you might not want that open for the
+full lifetime of the resource if you only change state occasionally.
+2. Suppose you came up with a really good reason why you wanted the two methods
+to be separate. It turns out that the current `CheckApply` can wrap this easily.
+It would look approximately like this:
+
+```golang
+func (obj *FooRes) CheckApply(ctx context.Context, apply bool) (bool, error) {
+	// my private split implementation of check and apply
+	if c, err := obj.check(ctx); err != nil {
+		return false, err // we errored
+	} else if c {
+		return true, nil // state was good!
+	}
+
+	if !apply {
+		return false, nil // state needs fixing, but apply is false
+	}
+
+	err := obj.apply(ctx) // errors if failure or unable to apply
+
+	return false, err // always return false, with an optional error
+}
+```
+
+Feel free to use this pattern if you're convinced it's necessary. Alternatively,
+if you think I got the `Res` API wrong and you have an improvement, please let
+us know!
+
+### Why do resources have both a `Cmp` method and an `IFF` (on the UID) method?
+
+The `Cmp()` methods are for determining if two resources are effectively the
+same, which is used to make graph change delta's efficient. This is when we want
+to change from the current running graph to a new graph, but preserve the common
+vertices. Since we want to make this process efficient, we only update the parts
+that are different, and leave everything else alone. This `Cmp()` method can
+tell us if two resources are the same. In case it is not obvious, `cmp` is an
+abbrev. for compare.
+
+The `IFF()` method is part of the whole UID system, which is for discerning if a
+resource meets the requirements another expects for an automatic edge. This is
+because the automatic edge system assumes a unified UID pattern to test for
+equality. In the future it might be helpful or sane to merge the two similar
+comparison functions although for now they are separate because they are
+actually answer different questions.
+
+### What new resource primitives need writing?
+
+There are still many ideas for new resources that haven't been written yet. If
+you'd like to contribute one, please contact us and tell us about your idea!
+
+### Is the resource API stable? Does it ever change?
+
+Since we are pre 1.0, the resource API is not guaranteed to be stable, however
+it is not expected to change significantly. The last major change kept the
+core functionality nearly identical, simplified the implementation of all the
+resources, and took about five to ten minutes to port each resource to the new
+API. The fundamental logic and behaviour behind the resource API has not changed
+since it was initially introduced.
+
+### Where can I find more information about mgmt?
+
+Additional blog posts, videos and other material [is available!](https://github.com/purpleidea/mgmt/blob/master/docs/on-the-web.md).
+
+## Suggestions
+
+If you have any ideas for API changes or other improvements to resource writing,
+please let us know! We're still pre 1.0 and pre 0.1 and happy to break API in
+order to get it right!

docs/resources.md

@@ -0,0 +1,250 @@
+# Resources
+
+Here we list all the built-in resources and their properties. The resource
+primitives in `mgmt` are typically more powerful than resources in other
+configuration management systems because they can be event based which lets them
+respond in real-time to converge to the desired state. This property allows you
+to build more complex resources that you probably hadn't considered in the past.
+
+In addition to the resource specific properties, there are resource properties
+(otherwise known as parameters) which can apply to every resource. These are
+called [meta parameters](documentation.md#meta-parameters) and are listed
+separately. Certain meta parameters aren't very useful when combined with
+certain resources, but in general, it should be fairly obvious, such as when
+combining the `noop` meta parameter with the [Noop](#Noop) resource.
+
+You might want to look at the [generated documentation](https://godoc.org/github.com/purpleidea/mgmt/engine/resources)
+for more up-to-date information about these resources.
+
+* [Augeas](#Augeas): Manipulate files using augeas.
+* [Consul:KV](#ConsulKV): Set keys in a Consul datastore.
+* [Docker](#Docker):[Container](#Container) Manage docker containers.
+* [Exec](#Exec): Execute shell commands on the system.
+* [File](#File): Manage files and directories.
+* [Group](#Group): Manage system groups.
+* [Hostname](#Hostname): Manages the hostname on the system.
+* [KV](#KV): Set a key value pair in our shared world database.
+* [Msg](#Msg): Send log messages.
+* [Net](#Net): Manage a local network interface.
+* [Noop](#Noop): A simple resource that does nothing.
+* [Nspawn](#Nspawn): Manage systemd-machined nspawn containers.
+* [Password](#Password): Create random password strings.
+* [Pkg](#Pkg):  Manage system packages with PackageKit.
+* [Print](#Print): Print messages to the console.
+* [Svc](#Svc): Manage system systemd services.
+* [Test](#Test): A mostly harmless resource that is used for internal testing.
+* [Tftp:File](#TftpFile): Add files to the small embedded embedded tftp server.
+* [Tftp:Server](#TftpServer): Run a small embedded tftp server.
+* [Timer](#Timer): Manage system systemd services.
+* [User](#User): Manage system users.
+* [Virt](#Virt): Manage virtual machines with libvirt.
+
+## Augeas
+
+The augeas resource uses [augeas](http://augeas.net/) commands to manipulate
+files.
+
+## Docker
+
+### Container
+
+The docker:container resource manages docker containers.
+
+It has the following properties:
+
+* `state`: either `running`, `stopped`, or `removed`
+* `image`: docker `image` or `image:tag`
+* `cmd`: a command or list of commands to run on the container
+* `env`: a list of environment variables, e.g. `["VAR=val",],`
+* `ports`: a map of portmappings, e.g. `{"tcp" => {80 => 8080, 443 => 8443,},},`
+* `apiversion:` override the host's default docker version, e.g. `"v1.35"`
+* `force`: destroy and rebuild the container instead of erroring on wrong image
+
+## Exec
+
+The exec resource can execute commands on your system.
+
+## File
+
+The file resource manages files and directories. In `mgmt`, directories are
+identified by a trailing slash in their path name. File have no such slash.
+
+It has the following properties:
+
+* `path`: absolute file path (directories have a trailing slash here)
+* `state`: either `exists`, `absent`, or undefined
+* `content`: raw file content
+* `mode`: octal unix file permissions or symbolic string
+* `owner`: username or uid for the file owner
+* `group`: group name or gid for the file group
+
+### Path
+
+The path property specifies the file or directory that we are managing.
+
+### State
+
+The state property describes the action we'd like to apply for the resource. The
+possible values are: `exists` and `absent`. If you do not specify either of
+these, it is undefined. Without specifying this value as `exists`, another param
+cannot cause a file to get implicitly created. When specifying this value as
+`absent`, you should not specify any other params that would normally change the
+file. For example, if you specify `content` and this param is `absent`, then you
+will get an engine validation error.
+
+### Content
+
+The content property is a string that specifies the desired file contents.
+
+### Source
+
+The source property points to a source file or directory path that we wish to
+copy over and use as the desired contents for our resource.
+
+### Fragments
+
+The fragments property lets you specify a list of files to concatenate together
+to make up the contents of this file. They will be combined in the order that
+they are listed in. If one of the files specified is a directory, then the
+files in that top-level directory will be themselves combined together and used.
+
+### Recurse
+
+The recurse property limits whether file resource operations should recurse into
+and monitor directory contents with a depth greater than one.
+
+### Force
+
+The force property is required if we want the file resource to be able to change
+a file into a directory or vice-versa. If such a change is needed, but the force
+property is not set to `true`, then this file resource will error.
+
+### Purge
+
+The purge property is used when this file represents a directory, and we'd like
+to remove any unmanaged files from within it. Please note that any unmanaged
+files in a directory with this flag set will be irreversibly deleted.
+
+## Group
+
+The group resource manages the system groups from `/etc/group`.
+
+## Hostname
+
+The hostname resource manages static, transient/dynamic and pretty hostnames
+on the system and watches them for changes.
+
+### static_hostname
+
+The static hostname is the one configured in /etc/hostname or a similar
+file.
+It is chosen by the local user. It is not always in sync with the current
+host name as returned by the gethostname() system call.
+
+### transient_hostname
+
+The transient / dynamic hostname is the one configured via the kernel's
+sethostbyname().
+It can be different from the static hostname in case DHCP or mDNS have been
+configured to change the name based on network information.
+
+### pretty_hostname
+
+The pretty hostname is a free-form UTF8 host name for presentation to the user.
+
+### hostname
+
+Hostname is the fallback value for all 3 fields above, if only `hostname` is
+specified, it will set all 3 fields to this value.
+
+## KV
+
+The KV resource sets a key and value pair in the global world database. This is
+quite useful for setting a flag after a number of resources have run. It will
+ignore database updates to the value that are greater in compare order than the
+requested key if the `SkipLessThan` parameter is set to true. If we receive a
+refresh, then the stored value will be reset to the requested value even if the
+stored value is greater.
+
+### Key
+
+The string key used to store the key.
+
+### Value
+
+The string value to set. This can also be set via Send/Recv.
+
+### SkipLessThan
+
+If this parameter is set to `true`, then it will ignore updating the value as
+long as the database versions are greater than the requested value. The compare
+operation used is based on the `SkipCmpStyle` parameter.
+
+### SkipCmpStyle
+
+By default this converts the string values to integers and compares them as you
+would expect.
+
+## Msg
+
+The msg resource sends messages to the main log, or an external service such
+as systemd's journal.
+
+## Net
+
+The net resource manages a local network interface using netlink.
+
+## Noop
+
+The noop resource does absolutely nothing. It does have some utility in testing
+`mgmt` and also as a placeholder in the resource graph.
+
+## Nspawn
+
+The nspawn resource is used to manage systemd-machined style containers.
+
+## Password
+
+The password resource can generate a random string to be used as a password. It
+will re-generate the password if it receives a refresh notification.
+
+## Pkg
+
+The pkg resource is used to manage system packages. This resource works on many
+different distributions because it uses the underlying packagekit facility which
+supports different backends for different environments. This ensures that we
+have great Debian (deb/dpkg) and Fedora (rpm/dnf) support simultaneously.
+
+## Print
+
+The print resource prints messages to the console.
+
+## Svc
+
+The service resource is still very WIP. Please help us by improving it!
+
+## Test
+
+The test resource is mostly harmless and is used for internal tests.
+
+## Tftp:File
+
+This adds files to the running tftp server. It's useful because it allows you to
+add individual files without needing to create them on disk.
+
+## Tftp:Server
+
+Run a small embedded tftp server. This doesn't apply any state, but instead runs
+a pure golang tftp server in the Watch loop.
+
+## Timer
+
+This resource needs better documentation. Please help us by improving it!
+
+## User
+
+The user resource manages the system users from `/etc/passwd`.
+
+## Virt
+
+The virt resource can manage virtual machines via libvirt.

docs/style-guide.md

@@ -0,0 +1,243 @@
+# Style guide
+
+This document aims to be a reference for the desired style for patches to mgmt,
+and the associated `mcl` language. In particular it describes conventions which
+are not officially enforced by tools and in test cases, or that aren't clearly
+defined elsewhere. We try to turn as many of these into automated tests as we
+can. If something here is not defined in a test, or you think it should be,
+please write one! Even better, you can write a tool to automatically fix it,
+since this is more useful and can easily be turned into a test!
+
+## Overview for golang code
+
+Most style issues are enforced by the `gofmt` tool. Other style aspects are
+often common sense to seasoned programmers, and we hope this will be a useful
+reference for new programmers.
+
+There are a lot of useful code review comments described
+[here](https://github.com/golang/go/wiki/CodeReviewComments). We don't
+necessarily follow everything strictly, but it is in general a very good guide.
+
+### Basics
+
+* All of our golang code is formatted with `gofmt`.
+
+### Comments
+
+All of our code is commented with the minimums required for `godoc` to function,
+and so that our comments pass `golint`. Code comments should either be full
+sentences (which end with a period, use proper punctuation, and capitalize the
+first word when it is not a lower cased identifier), or are short one-line
+comments in the source which are not full sentences and don't end with a period.
+
+They should explain algorithms, describe non-obvious behaviour, or situations
+which would otherwise need explanation or additional research during a code
+review. Notes about use of unfamiliar API's is a good idea for a code comment.
+
+#### Example
+
+Here you can see a function with the correct `godoc` string. The first word must
+match the name of the function. It is _not_ capitalized because the function is
+private.
+
+```golang
+// square multiplies the input integer by itself and returns this product.
+func square(x int) int {
+	return x * x // we don't care about overflow errors
+}
+```
+
+### Line length
+
+In general we try to stick to 80 character lines when it is appropriate. It is
+almost *always* appropriate for function `godoc` comments and most longer
+paragraphs. Exceptions are always allowed based on the will of the maintainer.
+
+It is usually better to exceed 80 characters than to break code unnecessarily.
+If your code often exceeds 80 characters, it might be an indication that it
+needs refactoring.
+
+Occasionally inline, two line source code comments are used within a function.
+These should usually be balanced so that you don't have one line with 78
+characters and the second with only four. Split the comment between the two.
+
+### Default values
+
+Whenever a constant or function parameter is defined, try and have the safer or
+default value be the `zero` value. For example, instead of `const NoDanger`, use
+`const AllowDanger` so that the `false` value is the safe scenario.
+
+### Method receiver naming
+
+[Contrary](https://github.com/golang/go/wiki/CodeReviewComments#receiver-names)
+to the specialized naming of the method receiver variable, we usually name all
+of these `obj` for ease of code copying throughout the project, and for faster
+identification when reviewing code. Some anecdotal studies have shown that it
+makes the code easier to read since you don't need to remember the name of the
+method receiver variable in each different method. This is very similar to what
+is done in `python`.
+
+#### Example
+
+```golang
+// Bar does a thing, and returns the number of baz results found in our
+database.
+func (obj *Foo) Bar(baz string) int {
+	if len(obj.s) > 0 {
+		return strings.Count(obj.s, baz)
+	}
+	return -1
+}
+```
+
+### Variable naming
+
+We prefer shorter, scoped variables rather than `unnecessarilyLongIdentifiers`.
+Remember the scoping rules and feel free to use new variables where appropriate.
+For example, in a short string snippet you can use `s` instead of `myString`, as
+well as other common choices. `i` is a common `int` counter, `f` for files, `fn`
+for functions, `x` for something else and so on.
+
+### Variable re-use
+
+Feel free to create and use new variables instead of attempting to re-use the
+same string. For example, if a function input arg is named `s`, you can use a
+new variable to receive the first computation result on `s` instead of storing
+it back into the original `s`. This avoids confusion if a different part of the
+code wants to read the original input, and it avoids any chance of edit by
+reference of the original callers copy of the variable.
+
+#### Example
+
+```golang
+MyNotIdealFunc(s string, b bool) string {
+	if !b {
+		return s + "hey"
+	}
+	s = strings.Replace(s, "blah", "", -1) // not ideal (re-use of `s` var)
+	return s
+}
+
+MyOkayFunc(s string, b bool) string {
+	if !b {
+		return s + "hey"
+	}
+	s2 := strings.Replace(s, "blah", "", -1) // doesn't re-use `s` variable
+	return s2
+}
+
+MyGreatFunc(s string, b bool) string {
+	if !b {
+		return s + "hey"
+	}
+	return strings.Replace(s, "blah", "", -1) // even cleaner
+}
+```
+
+### Constants in code
+
+If a function takes a specifier (often a bool) it's sometimes better to name
+that variable (often with a `const`) rather than leaving a naked `bool` in the
+code. For example, `x := MyFoo("blah", false)` is less clear than
+`const useMagic = false; x := MyFoo("blah", useMagic)`.
+
+### Empty slice declarations
+
+When declaring a new empty slice, there are three different mechanisms:
+
+1. `a := []string{}`
+
+2. `var a []string`
+
+3. `a := make([]string, 0)`
+
+In general, we prefer the first method because we find that it is succinct, and
+very readable. The third method is the least recommended because you're adding
+extra data that a smart compiler could probably figure out on its own. There are
+performance implications between these three methods, so unless your code is in
+a fast path or memory constrained environment where this matters (and that you
+ideally have proof of this) please use the methods as ordered as much as
+possible.
+
+### Consistent ordering
+
+In general we try to preserve a logical ordering in source files which usually
+matches the common order of execution that a _lazy evaluator_ would follow.
+
+This is also the order which is recommended when creating interface types. When
+implementing an interface, arrange your methods in the same order that they are
+declared in the interface.
+
+When implementing code for the various types in the language, please follow this
+order: `bool`, `str`, `int`, `float`, `list`, `map`, `struct`, `func`.
+
+For other aspects where you have a set of items, try to be internally consistent
+as well. For example, if you have two switch statements with `A`, `B`, and `C`,
+please use the same ordering for these elements elsewhere that they appear in
+the code and in the commentary if it is not illogical to do so.
+
+### Product identifiers
+
+Try to avoid references in the code to `mgmt` or a specific program name string
+if possible. This makes it easier to rename code if we ever pick a better name
+or support `libmgmt` better if we embed it. You can use the `Program` variable
+which is available in numerous places if you want a string to put in the logs.
+
+It is also recommended to avoid the `go` (programming language name) string if
+possible. Try to use `golang` if required, since the word `go` is already
+overloaded, and in particular it was even already used by the
+[`go!`](https://en.wikipedia.org/wiki/Go!_(programming_language)).
+
+## Overview for mcl code
+
+The `mcl` language is quite new, so this guide will probably change over time as
+we find what's best, and hopefully we'll be able to add an `mclfmt` tool in the
+future so that less of this needs to be documented. (Patches welcome!)
+
+### Indentation
+
+Code indentation is done with tabs. The tab-width is a private preference, which
+is the beauty of using tabs: you can have your own personal preference. The
+inventor of `mgmt` uses and recommends a width of eight, and that is what should
+be used if your tool requires a modeline to be publicly committed.
+
+### Line length
+
+We recommend you stick to 80 char line width. If you find yourself with deeper
+nesting, it might be a hint that your code could be refactored in a more
+pleasant way.
+
+### Capitalization
+
+At the moment, variables, function names, and classes are all lowercase and do
+not contain underscores. We will probably figure out what style to recommend
+when the language is a bit further along. For example, we haven't decided if we
+should have a notion of public and private variables, and if we'd like to
+reserve capitalization for this situation.
+
+### Module naming
+
+We recommend you name your modules with an `mgmt-` prefix. For example, a module
+about bananas might be named `mgmt-banana`. This is helpful for the useful magic
+built-in to the module import code, which will by default take a remote import
+like: `import "https://github.com/purpleidea/mgmt-banana/"` and namespace it as
+`banana`. Of course you can always pick the namespace yourself on import with:
+`import "https://github.com/purpleidea/mgmt-banana/" as tomato` or something
+similar.
+
+### Licensing
+
+We believe that sharing code helps reduce unnecessary re-invention, so that we
+can [stand on the shoulders of giants](https://en.wikipedia.org/wiki/Standing_on_the_shoulders_of_giants)
+and hopefully make faster progress in science, medicine, exploration, etc... As
+a result, we recommend releasing your modules under the [LGPLv3+](https://www.gnu.org/licenses/lgpl-3.0.en.html)
+license for the maximum balance of freedom and re-usability. We strongly oppose
+any [CLA](https://en.wikipedia.org/wiki/Contributor_License_Agreement)
+requirements and believe that the ["inbound==outbound"](https://ref.fedorapeople.org/fontana-linuxcon.html#slide2)
+rule applies. Lastly, we do not support software patents and we hope you don't
+either!
+
+## Suggestions
+
+If you have any ideas for suggestions or other improvements to this guide,
+please let us know!

engine/autoedge.go

@@ -0,0 +1,138 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package engine
+
+import (
+	"fmt"
+)
+
+// EdgeableRes is the interface a resource must implement to support automatic
+// edges. Both the vertices involved in an edge need to implement this for it to
+// be able to work.
+type EdgeableRes interface {
+	Res // implement everything in Res but add the additional requirements
+
+	// AutoEdgeMeta lets you get or set meta params for the automatic edges
+	// trait.
+	AutoEdgeMeta() *AutoEdgeMeta
+
+	// SetAutoEdgeMeta lets you set all of the meta params for the automatic
+	// edges trait in a single call.
+	SetAutoEdgeMeta(*AutoEdgeMeta)
+
+	// UIDs includes all params to make a unique identification of this
+	// object.
+	UIDs() []ResUID // most resources only return one
+
+	// AutoEdges returns a struct that implements the AutoEdge interface.
+	// This interface can be used to generate automatic edges to other
+	// resources.
+	AutoEdges() (AutoEdge, error)
+}
+
+// AutoEdgeMeta provides some parameters specific to automatic edges.
+// TODO: currently this only supports disabling the feature per-resource, but in
+// the future you could conceivably have some small pattern to control it better
+type AutoEdgeMeta struct {
+	// Disabled specifies that automatic edges should be disabled for this
+	// resource.
+	Disabled bool
+}
+
+// Cmp compares two AutoEdgeMeta structs and determines if they're equivalent.
+func (obj *AutoEdgeMeta) Cmp(aem *AutoEdgeMeta) error {
+	if obj.Disabled != aem.Disabled {
+		return fmt.Errorf("values for Disabled are different")
+	}
+	return nil
+}
+
+// The AutoEdge interface is used to implement the autoedges feature.
+type AutoEdge interface {
+	Next() []ResUID   // call to get list of edges to add
+	Test([]bool) bool // call until false
+}
+
+// ResUID is a unique identifier for a resource, namely it's name, and the kind
+// ("type").
+type ResUID interface {
+	fmt.Stringer // String() string
+
+	GetName() string
+	GetKind() string
+
+	IFF(ResUID) bool
+
+	IsReversed() bool // true means this resource happens before the generator
+}
+
+// The BaseUID struct is used to provide a unique resource identifier.
+type BaseUID struct {
+	Name string // name and kind are the values of where this is coming from
+	Kind string
+
+	Reversed *bool // piggyback edge information here
+}
+
+// GetName returns the name of the resource UID.
+func (obj *BaseUID) GetName() string {
+	return obj.Name
+}
+
+// GetKind returns the kind of the resource UID.
+func (obj *BaseUID) GetKind() string {
+	return obj.Kind
+}
+
+// String returns the canonical string representation for a resource UID.
+func (obj *BaseUID) String() string {
+	return fmt.Sprintf("%s[%s]", obj.GetKind(), obj.GetName())
+}
+
+// IFF looks at two UID's and if and only if they are equivalent, returns true.
+// If they are not equivalent, it returns false. Most resources will want to
+// override this method, since it does the important work of actually discerning
+// if two resources are identical in function.
+func (obj *BaseUID) IFF(uid ResUID) bool {
+	res, ok := uid.(*BaseUID)
+	if !ok {
+		return false
+	}
+	return obj.Name == res.Name
+}
+
+// IsReversed is part of the ResUID interface, and true means this resource
+// happens before the generator.
+func (obj *BaseUID) IsReversed() bool {
+	if obj.Reversed == nil {
+		panic("programming error!")
+	}
+	return *obj.Reversed
+}

engine/autoedge_test.go

@@ -0,0 +1,50 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+//go:build !root
+
+package engine
+
+import (
+	"testing"
+)
+
+func TestIFF1(t *testing.T) {
+	uid := &BaseUID{Name: "/tmp/unit-test"}
+	same := &BaseUID{Name: "/tmp/unit-test"}
+	diff := &BaseUID{Name: "/tmp/other-file"}
+
+	if !uid.IFF(same) {
+		t.Errorf("basic resource UIDs with the same name should satisfy each other's IFF condition")
+	}
+
+	if uid.IFF(diff) {
+		t.Errorf("basic resource UIDs with different names should NOT satisfy each other's IFF condition")
+	}
+}

engine/autogroup.go

@@ -0,0 +1,108 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package engine
+
+import (
+	"fmt"
+
+	"github.com/purpleidea/mgmt/pgraph"
+)
+
+// GroupableRes is the interface a resource must implement to support automatic
+// grouping. Default implementations for most of the methods declared in this
+// interface can be obtained for your resource by anonymously adding the
+// traits.Groupable struct to your resource implementation.
+type GroupableRes interface {
+	Res // implement everything in Res but add the additional requirements
+
+	// AutoGroupMeta lets you get or set meta params for the automatic
+	// grouping trait.
+	AutoGroupMeta() *AutoGroupMeta
+
+	// SetAutoGroupMeta lets you set all of the meta params for the
+	// automatic grouping trait in a single call.
+	SetAutoGroupMeta(*AutoGroupMeta)
+
+	// GroupCmp compares two resources and decides if they're suitable for
+	// grouping. This usually needs to be unique to your resource.
+	GroupCmp(res GroupableRes) error
+
+	// GroupRes groups resource argument (res) into self. Callers of this
+	// method should probably also run SetParent.
+	GroupRes(res GroupableRes) error
+
+	// IsGrouped determines if we are grouped.
+	IsGrouped() bool // am I grouped?
+
+	// SetGrouped sets a flag to tell if we are grouped.
+	SetGrouped(bool)
+
+	// GetGroup returns everyone grouped inside me.
+	GetGroup() []GroupableRes // return everyone grouped inside me
+
+	// SetGroup sets the grouped resources into me. Callers of this method
+	// should probably also run SetParent.
+	SetGroup([]GroupableRes)
+
+	// Parent returns the parent groupable resource that I am inside of.
+	Parent() GroupableRes
+
+	// SetParent tells a particular grouped resource who their parent is.
+	SetParent(res GroupableRes)
+}
+
+// AutoGroupMeta provides some parameters specific to automatic grouping.
+// TODO: currently this only supports disabling the feature per-resource, but in
+// the future you could conceivably have some small pattern to control it better
+type AutoGroupMeta struct {
+	// Disabled specifies that automatic grouping should be disabled for
+	// this resource.
+	Disabled bool
+}
+
+// Cmp compares two AutoGroupMeta structs and determines if they're equivalent.
+func (obj *AutoGroupMeta) Cmp(agm *AutoGroupMeta) error {
+	if obj.Disabled != agm.Disabled {
+		return fmt.Errorf("values for Disabled are different")
+	}
+	return nil
+}
+
+// AutoGrouper is the required interface to implement an autogrouping algorithm.
+type AutoGrouper interface {
+	// listed in the order these are typically called in...
+	Name() string                                                    // friendly identifier
+	Init(*pgraph.Graph) error                                        // only call once
+	VertexNext() (pgraph.Vertex, pgraph.Vertex, error)               // mostly algorithmic
+	VertexCmp(pgraph.Vertex, pgraph.Vertex) error                    // can we merge these ?
+	VertexMerge(pgraph.Vertex, pgraph.Vertex) (pgraph.Vertex, error) // vertex merge fn to use
+	EdgeMerge(pgraph.Edge, pgraph.Edge) pgraph.Edge                  // edge merge fn to use
+	VertexTest(bool) (bool, error)                                   // call until false
+}

engine/cmp.go

@@ -0,0 +1,449 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package engine
+
+import (
+	"fmt"
+
+	"github.com/purpleidea/mgmt/pgraph"
+	"github.com/purpleidea/mgmt/util/errwrap"
+)
+
+// ResCmp compares two resources by checking multiple aspects. This is the main
+// entry point for running all the compare steps on two resources. This code is
+// very similar to AdaptCmp.
+func ResCmp(r1, r2 Res) error {
+	if r1.Kind() != r2.Kind() {
+		return fmt.Errorf("kind differs")
+	}
+	if r1.Name() != r2.Name() {
+		return fmt.Errorf("name differs")
+	}
+
+	if err := r1.Cmp(r2); err != nil {
+		return err
+	}
+
+	// TODO: do we need to compare other traits/metaparams?
+
+	m1 := r1.MetaParams()
+	m2 := r2.MetaParams()
+	if (m1 == nil) != (m2 == nil) { // xor
+		return fmt.Errorf("meta params differ")
+	}
+	if m1 != nil && m2 != nil {
+		if err := m1.Cmp(m2); err != nil {
+			return err
+		}
+	}
+
+	r1x, ok1 := r1.(RefreshableRes)
+	r2x, ok2 := r2.(RefreshableRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("refreshable differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		if r1x.Refresh() != r2x.Refresh() {
+			return fmt.Errorf("refresh differs")
+		}
+	}
+
+	// compare meta params for resources with auto edges
+	r1e, ok1 := r1.(EdgeableRes)
+	r2e, ok2 := r2.(EdgeableRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("edgeable differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		if r1e.AutoEdgeMeta().Cmp(r2e.AutoEdgeMeta()) != nil {
+			return fmt.Errorf("autoedge differs")
+		}
+	}
+
+	// compare meta params for resources with auto grouping
+	r1g, ok1 := r1.(GroupableRes)
+	r2g, ok2 := r2.(GroupableRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("groupable differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		if r1g.AutoGroupMeta().Cmp(r2g.AutoGroupMeta()) != nil {
+			return fmt.Errorf("autogroup differs")
+		}
+
+		// if resources are grouped, are the groups the same?
+		if i, j := r1g.GetGroup(), r2g.GetGroup(); len(i) != len(j) {
+			return fmt.Errorf("autogroup groups differ")
+		} else if len(i) > 0 { // trick the golinter
+
+			// Sort works with Res, so convert the lists to that
+			iRes := []Res{}
+			for _, r := range i {
+				res := r.(Res)
+				iRes = append(iRes, res)
+			}
+			jRes := []Res{}
+			for _, r := range j {
+				res := r.(Res)
+				jRes = append(jRes, res)
+			}
+
+			ix, jx := Sort(iRes), Sort(jRes) // now sort :)
+			for k := range ix {
+				// compare sub resources
+				if err := ResCmp(ix[k], jx[k]); err != nil {
+					//fmt.Printf("bad Cmp: %+v <> %+v for: %+v <> %+v err: %+v\n", r1, r2, ix[k], jx[k], err)
+					return err
+				}
+			}
+		}
+	}
+
+	r1r, ok1 := r1.(RecvableRes)
+	r2r, ok2 := r2.(RecvableRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("recvable differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		v1 := r1r.Recv()
+		v2 := r2r.Recv()
+
+		// XXX: Our Send/Recv in the lib/main.go doesn't seem to be
+		// pulling this in, so this always compares differently. We can
+		// comment it out for now, since it's not too consequential.
+		// XXX: Find out what the issue is and fix it for here and send.
+		// XXX: The below errors are commented out until this is fixed.
+		if (v1 == nil) != (v2 == nil) { // xor
+			//return fmt.Errorf("recv params differ")
+		}
+		if v1 != nil && v2 != nil {
+			if len(v1) != len(v2) {
+				//return fmt.Errorf("recv param lengths differ")
+			}
+			for key, send1 := range v1 { // map[string]*engine.Send
+				send2, exists := v2[key]
+				if !exists {
+					//return fmt.Errorf("recv param key %s doesn't exist", key)
+				}
+				if (send1 == nil) != (send2 == nil) { // xor
+					//return fmt.Errorf("recv param key %s send differs", key)
+				}
+				if send1 != nil && send2 != nil && send1.Key != send2.Key {
+					//return fmt.Errorf("recv param key %s send key differs (%v != %v)", key, send1.Key, send2.Key)
+				}
+			}
+		}
+	}
+
+	r1s, ok1 := r1.(SendableRes)
+	r2s, ok2 := r2.(SendableRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("sendable differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		s1 := r1s.Sent()
+		s2 := r2s.Sent()
+
+		// XXX: Our Send/Recv in the lib/main.go doesn't seem to be
+		// pulling this in, so this always compares differently. We can
+		// comment it out for now, since it's not too consequential.
+		// XXX: Find out what the issue is and fix it for here and recv.
+		// XXX: The below errors are commented out until this is fixed.
+		if (s1 == nil) != (s2 == nil) { // xor
+			//return fmt.Errorf("send params differ")
+		}
+		if s1 != nil && s2 != nil {
+			// TODO: reflect.DeepEqual?
+			//return fmt.Errorf("send params exist")
+		}
+	}
+
+	// compare meta params for resources with reversible traits
+	r1v, ok1 := r1.(ReversibleRes)
+	r2v, ok2 := r2.(ReversibleRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("reversible differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		if r1v.ReversibleMeta().Cmp(r2v.ReversibleMeta()) != nil {
+			return fmt.Errorf("reversible differs")
+		}
+	}
+
+	return nil
+}
+
+// AdaptCmp compares two resources by checking multiple aspects. This is the
+// main entry point for running all the compatible compare steps on two
+// resources. This code is very similar to ResCmp.
+func AdaptCmp(r1, r2 CompatibleRes) error {
+	if r1.Kind() != r2.Kind() {
+		return fmt.Errorf("kind differs")
+	}
+	if r1.Name() != r2.Name() {
+		return fmt.Errorf("name differs")
+	}
+
+	// run `Adapts` instead of `Cmp`
+	if err := r1.Adapts(r2); err != nil {
+		return err
+	}
+
+	// TODO: do we need to compare other traits/metaparams?
+
+	m1 := r1.MetaParams()
+	m2 := r2.MetaParams()
+	if (m1 == nil) != (m2 == nil) { // xor
+		return fmt.Errorf("meta params differ")
+	}
+	if m1 != nil && m2 != nil {
+		if err := m1.Cmp(m2); err != nil {
+			return err
+		}
+	}
+
+	// we don't need to compare refresh, since those can always be merged...
+
+	// compare meta params for resources with auto edges
+	r1e, ok1 := r1.(EdgeableRes)
+	r2e, ok2 := r2.(EdgeableRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("edgeable differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		if r1e.AutoEdgeMeta().Cmp(r2e.AutoEdgeMeta()) != nil {
+			return fmt.Errorf("autoedge differs")
+		}
+	}
+
+	// compare meta params for resources with auto grouping
+	r1g, ok1 := r1.(GroupableRes)
+	r2g, ok2 := r2.(GroupableRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("groupable differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		if r1g.AutoGroupMeta().Cmp(r2g.AutoGroupMeta()) != nil {
+			return fmt.Errorf("autogroup differs")
+		}
+
+		// if resources are grouped, are the groups the same?
+		if i, j := r1g.GetGroup(), r2g.GetGroup(); len(i) != len(j) {
+			return fmt.Errorf("autogroup groups differ")
+		} else if len(i) > 0 { // trick the golinter
+
+			// Sort works with Res, so convert the lists to that
+			iRes := []Res{}
+			for _, r := range i {
+				res := r.(Res)
+				iRes = append(iRes, res)
+			}
+			jRes := []Res{}
+			for _, r := range j {
+				res := r.(Res)
+				jRes = append(jRes, res)
+			}
+
+			ix, jx := Sort(iRes), Sort(jRes) // now sort :)
+			for k := range ix {
+				// compare sub resources
+				// TODO: should we use AdaptCmp here?
+				// TODO: how would they run `Merge` ? (we don't)
+				// this code path will probably not run, because
+				// it is called in the lang before autogrouping!
+				if err := ResCmp(ix[k], jx[k]); err != nil {
+					return err
+				}
+			}
+		}
+	}
+
+	r1r, ok1 := r1.(RecvableRes)
+	r2r, ok2 := r2.(RecvableRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("recvable differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		v1 := r1r.Recv()
+		v2 := r2r.Recv()
+
+		// XXX: Our Send/Recv in the lib/main.go doesn't seem to be
+		// pulling this in, so this always compares differently. We can
+		// comment it out for now, since it's not too consequential.
+		// XXX: Find out what the issue is and fix it for here and send.
+		// XXX: The below errors are commented out until this is fixed.
+		if (v1 == nil) != (v2 == nil) { // xor
+			//return fmt.Errorf("recv params differ")
+		}
+		if v1 != nil && v2 != nil {
+			if len(v1) != len(v2) {
+				//return fmt.Errorf("recv param lengths differ")
+			}
+			for key, send1 := range v1 { // map[string]*engine.Send
+				send2, exists := v2[key]
+				if !exists {
+					//return fmt.Errorf("recv param key %s doesn't exist", key)
+				}
+				if (send1 == nil) != (send2 == nil) { // xor
+					//return fmt.Errorf("recv param key %s send differs", key)
+				}
+				if send1 != nil && send2 != nil && send1.Key != send2.Key {
+					//return fmt.Errorf("recv param key %s send key differs (%v != %v)", key, send1.Key, send2.Key)
+				}
+			}
+		}
+	}
+
+	r1s, ok1 := r1.(SendableRes)
+	r2s, ok2 := r2.(SendableRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("sendable differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		s1 := r1s.Sent()
+		s2 := r2s.Sent()
+
+		// XXX: Our Send/Recv in the lib/main.go doesn't seem to be
+		// pulling this in, so this always compares differently. We can
+		// comment it out for now, since it's not too consequential.
+		// XXX: Find out what the issue is and fix it for here and recv.
+		// XXX: The below errors are commented out until this is fixed.
+		if (s1 == nil) != (s2 == nil) { // xor
+			//return fmt.Errorf("send params differ")
+		}
+		if s1 != nil && s2 != nil {
+			// TODO: reflect.DeepEqual?
+			//return fmt.Errorf("send params exist")
+		}
+	}
+
+	// compare meta params for resources with reversible traits
+	r1v, ok1 := r1.(ReversibleRes)
+	r2v, ok2 := r2.(ReversibleRes)
+	if ok1 != ok2 {
+		return fmt.Errorf("reversible differs") // they must be different (optional)
+	}
+	if ok1 && ok2 {
+		if r1v.ReversibleMeta().Cmp(r2v.ReversibleMeta()) != nil {
+			return fmt.Errorf("reversible differs")
+		}
+	}
+
+	return nil
+}
+
+// VertexCmpFn returns if two vertices are equivalent. It errors if they can't
+// be compared because one is not a vertex. This returns true if equal.
+// TODO: shouldn't the first argument be an `error` instead?
+func VertexCmpFn(v1, v2 pgraph.Vertex) (bool, error) {
+	r1, ok := v1.(Res)
+	if !ok {
+		return false, fmt.Errorf("v1 is not a Res")
+	}
+	r2, ok := v2.(Res)
+	if !ok {
+		return false, fmt.Errorf("v2 is not a Res")
+	}
+
+	if err := ResCmp(r1, r2); err != nil {
+		//fmt.Printf("bad Cmp: %p %+v <> %p %+v err: %+v\n", r1, r1, r2, r2, err)
+		return false, nil
+	}
+	//fmt.Printf("ok Cmp: %p %+v <> %p %+v\n", r1, r1, r2, r2)
+
+	return true, nil
+}
+
+// EdgeCmpFn returns if two edges are equivalent. It errors if they can't be
+// compared because one is not an edge. This returns true if equal.
+// TODO: shouldn't the first argument be an `error` instead?
+func EdgeCmpFn(e1, e2 pgraph.Edge) (bool, error) {
+	edge1, ok := e1.(*Edge)
+	if !ok {
+		return false, fmt.Errorf("e1 is not an Edge")
+	}
+	edge2, ok := e2.(*Edge)
+	if !ok {
+		return false, fmt.Errorf("e2 is not an Edge")
+	}
+	return edge1.Cmp(edge2) == nil, nil
+}
+
+// ResGraphMapper compares two graphs, and gives us a mapping from new to old
+// based on the resource kind and name only. This allows us to know which
+// previous resource might have data to pass on to the new version in the next
+// generation.
+// FIXME: Optimize this for performance since it runs a lot...
+func ResGraphMapper(oldGraph, newGraph *pgraph.Graph) (map[RecvableRes]RecvableRes, error) {
+	mapper := make(map[RecvableRes]RecvableRes) // new -> old based on name and kind only?
+	cmp := func(r1, r2 Res) error {
+		if r1.Kind() != r2.Kind() {
+			return fmt.Errorf("kind differs")
+		}
+		if r1.Name() != r2.Name() {
+			return fmt.Errorf("name differs")
+		}
+		return nil
+	}
+
+	// XXX: run this as a topological sort or reverse topological sort?
+	for v := range newGraph.Adjacency() { // loop through the vertices (resources)
+		r, ok := v.(RecvableRes)
+		if !ok {
+			continue // skip
+		}
+		fn := func(vv pgraph.Vertex) (bool, error) {
+			rr, ok := vv.(Res)
+			if !ok {
+				return false, fmt.Errorf("not a Res")
+			}
+
+			if err := cmp(rr, r); err != nil {
+				return false, nil
+			}
+			return true, nil
+		}
+		vertex, err := oldGraph.VertexMatchFn(fn)
+		if err != nil {
+			return nil, errwrap.Wrapf(err, "VertexMatchFn failed")
+		}
+		if vertex == nil {
+			continue // skip (error?)
+		}
+		res, ok := vertex.(RecvableRes)
+		if !ok {
+			continue // skip (error?)
+		}
+
+		mapper[r] = res
+	}
+
+	return mapper, nil
+}

engine/copy.go

@@ -0,0 +1,183 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package engine
+
+import (
+	"fmt"
+
+	"github.com/purpleidea/mgmt/util/errwrap"
+)
+
+// ResCopy copies a resource. This is the main entry point for copying a
+// resource since it does all the common engine-level copying as well.
+func ResCopy(r CopyableRes) (CopyableRes, error) {
+	res := r.Copy()
+	res.SetKind(r.Kind())
+	res.SetName(r.Name())
+
+	if x, ok := r.(MetaRes); ok {
+		dst, ok := res.(MetaRes)
+		if !ok {
+			// programming error
+			panic("meta interfaces are illogical")
+		}
+		dst.SetMetaParams(x.MetaParams().Copy()) // copy b/c we have it
+	}
+
+	if x, ok := r.(RefreshableRes); ok {
+		dst, ok := res.(RefreshableRes)
+		if !ok {
+			// programming error
+			panic("refresh interfaces are illogical")
+		}
+		dst.SetRefresh(x.Refresh()) // no need to copy atm
+	}
+
+	// copy meta params for resources with auto edges
+	if x, ok := r.(EdgeableRes); ok {
+		dst, ok := res.(EdgeableRes)
+		if !ok {
+			// programming error
+			panic("autoedge interfaces are illogical")
+		}
+		dst.SetAutoEdgeMeta(x.AutoEdgeMeta()) // no need to copy atm
+	}
+
+	// copy meta params for resources with auto grouping
+	if x, ok := r.(GroupableRes); ok {
+		dst, ok := res.(GroupableRes)
+		if !ok {
+			// programming error
+			panic("autogroup interfaces are illogical")
+		}
+		dst.SetAutoGroupMeta(x.AutoGroupMeta()) // no need to copy atm
+
+		grouped := []GroupableRes{}
+		for _, g := range x.GetGroup() {
+			g0, ok := g.(CopyableRes)
+			if !ok {
+				return nil, fmt.Errorf("resource wasn't copyable")
+			}
+			g1, err := ResCopy(g0)
+			if err != nil {
+				return nil, err
+			}
+			g2, ok := g1.(GroupableRes)
+			if !ok {
+				return nil, fmt.Errorf("resource wasn't groupable")
+			}
+			g2.SetParent(dst) // store who my parent is
+			grouped = append(grouped, g2)
+		}
+		dst.SetGroup(grouped)
+	}
+
+	if x, ok := r.(RecvableRes); ok {
+		dst, ok := res.(RecvableRes)
+		if !ok {
+			// programming error
+			panic("recv interfaces are illogical")
+		}
+		dst.SetRecv(x.Recv()) // no need to copy atm
+	}
+
+	if x, ok := r.(SendableRes); ok {
+		dst, ok := res.(SendableRes)
+		if !ok {
+			// programming error
+			panic("send interfaces are illogical")
+		}
+		if err := dst.Send(x.Sent()); err != nil { // no need to copy atm
+			return nil, errwrap.Wrapf(err, "can't copy send")
+		}
+	}
+
+	// copy meta params for resources with reversible traits
+	if x, ok := r.(ReversibleRes); ok {
+		dst, ok := res.(ReversibleRes)
+		if !ok {
+			// programming error
+			panic("reversible interfaces are illogical")
+		}
+		dst.SetReversibleMeta(x.ReversibleMeta()) // no need to copy atm
+	}
+
+	return res, nil
+}
+
+// ResMerge merges a set of resources that are compatible with each other. This
+// is the main entry point for the merging. They must each successfully be able
+// to run AdaptCmp without error.
+func ResMerge(r ...CompatibleRes) (CompatibleRes, error) {
+	if len(r) == 0 {
+		return nil, fmt.Errorf("zero resources given")
+	}
+	if len(r) == 1 {
+		return r[0], nil
+	}
+	if len(r) > 2 {
+		r0 := r[0]
+		r1, err := ResMerge(r[1:]...)
+		if err != nil {
+			return nil, err
+		}
+		return ResMerge(r0, r1)
+	}
+	// now we have r[0] and r[1] to merge here...
+	r0 := r[0]
+	r1 := r[1]
+	if err := AdaptCmp(r0, r1); err != nil {
+		return nil, err
+	}
+
+	res, err := r0.Merge(r1) // resource method of this interface
+	if err != nil {
+		return nil, err
+	}
+
+	// meta should have come over in the copy
+
+	if x, ok := res.(RefreshableRes); ok {
+		x0, ok0 := r0.(RefreshableRes)
+		x1, ok1 := r1.(RefreshableRes)
+		if !ok0 || !ok1 {
+			// programming error
+			panic("refresh interfaces are illogical")
+		}
+
+		x.SetRefresh(x0.Refresh() || x1.Refresh()) // true if either is!
+	}
+
+	// the other traits and metaparams can't be merged easily... so we don't
+	// merge them, and if they were present and differed, and weren't copied
+	// in the ResCopy method, then we should have errored above in AdaptCmp!
+
+	return res, nil
+}

engine/doc.go

@@ -0,0 +1,33 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+// Package engine represents the implementation of the resource engine that runs
+// the graph of resources in real-time. This package has the common imports that
+// most consumers use directly.
+package engine

engine/edge.go

@@ -0,0 +1,72 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package engine
+
+import (
+	"fmt"
+)
+
+// Edge is a struct that represents a graph's edge.
+type Edge struct {
+	Name   string
+	Notify bool // should we send a refresh notification along this edge?
+
+	refresh bool // is there a notify pending for the dest vertex ?
+}
+
+// String is a required method of the Edge interface that we must fulfill.
+func (obj *Edge) String() string {
+	return obj.Name
+}
+
+// Cmp compares this edge to another. It returns nil if they are equivalent.
+func (obj *Edge) Cmp(edge *Edge) error {
+	if obj.Name != edge.Name {
+		return fmt.Errorf("edge names differ")
+	}
+	if obj.Notify != edge.Notify {
+		return fmt.Errorf("notify values differ")
+	}
+	// FIXME: should we compare this as well?
+	//if obj.refresh != edge.refresh {
+	//	return fmt.Errorf("refresh values differ")
+	//}
+	return nil
+}
+
+// Refresh returns the pending refresh status of this edge.
+func (obj *Edge) Refresh() bool {
+	return obj.refresh
+}
+
+// SetRefresh sets the pending refresh status of this edge.
+func (obj *Edge) SetRefresh(b bool) {
+	obj.refresh = b
+}

engine/error.go

@@ -0,0 +1,44 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package engine
+
+// Error is a constant error type that implements error.
+type Error string
+
+// Error fulfills the error interface of this type.
+func (e Error) Error() string { return string(e) }
+
+const (
+	// ErrClosed means we couldn't complete a task because we had closed.
+	ErrClosed = Error("closed")
+
+	// ErrBackPoke means we're postponing due to a needed backpoke.
+	ErrBackPoke = Error("backpoke")
+)

engine/fs.go

@@ -0,0 +1,98 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package engine
+
+import (
+	"os"
+
+	"github.com/spf13/afero"
+)
+
+// Fs is an interface that represents the file system API that we support.
+// TODO: rename this to FS for consistency with the io/fs.FS naming scheme
+type Fs interface {
+	//fmt.Stringer // TODO: add this method?
+
+	// URI returns a unique string handle to access this filesystem.
+	URI() string // returns the URI for this file system
+
+	afero.Fs // TODO: why doesn't this interface exist in the os pkg?
+
+	// FS is the read-only filesystem interface from the io/fs.FS package.
+	//fs.FS // io/fs.FS
+
+	// ReadDir reads the named directory and returns a list of directory
+	// entries sorted by filename.
+	//
+	// This mimics the signature from io/fs.ReadDirFS and has the same docs.
+	//
+	// XXX: Not currently implemented because of legacy Afero.Fs above
+	//ReadDir(name string) ([]fs.DirEntry, error) // io/fs.ReadDirFS
+
+	// ReadFile reads the named file and returns its contents. A successful
+	// call returns a nil error, not io.EOF. (Because ReadFile reads the
+	// whole file, the expected EOF from the final Read is not treated as an
+	// error to be reported.)
+	//
+	// The caller is permitted to modify the returned byte slice. This
+	// method should return a copy of the underlying data.
+	//
+	// This mimics the signature from io/fs.ReadFileFS and has the same
+	// docs.
+	ReadFile(name string) ([]byte, error) // io/fs.ReadFileFS
+
+	// Stat returns a FileInfo describing the file. If there is an error, it
+	// should be of type *fs.PathError.
+	//
+	// This mimics the signature from io/fs.StatFS and has the same docs.
+	//
+	// XXX: Not currently implemented because of legacy Afero.Fs above
+	//Stat(name string) (FileInfo, error) // io/fs.StatFS
+
+	// afero.Fs versions:
+
+	ReadDir(dirname string) ([]os.FileInfo, error)
+}
+
+// WriteableFS is our internal filesystem interface for filesystems we write to.
+// It can wrap whatever implementations we want.
+type WriteableFS interface {
+	Fs
+
+	// WriteFile writes data to the named file, creating it if necessary. If
+	// the file does not exist, WriteFile creates it with permissions perm
+	// (before umask); otherwise WriteFile truncates it before writing,
+	// without changing permissions. Since Writefile requires multiple
+	// system calls to complete, a failure mid-operation can leave the file
+	// in a partially written state.
+	//
+	// This mimics the internal os.WriteFile function and has the same docs.
+	WriteFile(name string, data []byte, perm os.FileMode) error
+}

engine/graph/actions.go

@@ -0,0 +1,685 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package graph
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/purpleidea/mgmt/engine"
+	engineUtil "github.com/purpleidea/mgmt/engine/util"
+	"github.com/purpleidea/mgmt/pgraph"
+	"github.com/purpleidea/mgmt/util/errwrap"
+
+	"golang.org/x/time/rate"
+)
+
+// OKTimestamp returns true if this vertex can run right now.
+func (obj *Engine) OKTimestamp(vertex pgraph.Vertex) bool {
+	return len(obj.BadTimestamps(vertex)) == 0
+}
+
+// BadTimestamps returns the list of vertices that are causing our timestamp to
+// be bad.
+func (obj *Engine) BadTimestamps(vertex pgraph.Vertex) []pgraph.Vertex {
+	vs := []pgraph.Vertex{}
+	obj.state[vertex].mutex.RLock()   // concurrent read start
+	ts := obj.state[vertex].timestamp // race
+	obj.state[vertex].mutex.RUnlock() // concurrent read end
+	// these are all the vertices pointing TO vertex, eg: ??? -> vertex
+	for _, v := range obj.graph.IncomingGraphVertices(vertex) {
+		// If the vertex has a greater timestamp than any prerequisite,
+		// then we can't run right now. If they're equal (eg: initially
+		// with a value of 0) then we also can't run because we should
+		// let our pre-requisites go first.
+		obj.state[v].mutex.RLock()   // concurrent read start
+		t := obj.state[v].timestamp  // race
+		obj.state[v].mutex.RUnlock() // concurrent read end
+		if obj.Debug {
+			obj.Logf("OKTimestamp: %d >= %d (%s): !%t", ts, t, v.String(), ts >= t)
+		}
+		if ts >= t {
+			//return false
+			vs = append(vs, v)
+		}
+	}
+	return vs // formerly "true" if empty
+}
+
+// Process is the primary function to execute a particular vertex in the graph.
+func (obj *Engine) Process(ctx context.Context, vertex pgraph.Vertex) error {
+	res, isRes := vertex.(engine.Res)
+	if !isRes {
+		return fmt.Errorf("vertex is not a Res")
+	}
+
+	// backpoke! (can be async)
+	if vs := obj.BadTimestamps(vertex); len(vs) > 0 {
+		// back poke in parallel (sync b/c of waitgroup)
+		wg := &sync.WaitGroup{}
+		for _, v := range obj.graph.IncomingGraphVertices(vertex) {
+			if !pgraph.VertexContains(v, vs) { // only poke what's needed
+				continue
+			}
+
+			// doesn't really need to be in parallel, but we can...
+			wg.Add(1)
+			go func(vv pgraph.Vertex) {
+				defer wg.Done()
+				obj.state[vv].Poke() // async
+			}(v)
+
+		}
+		wg.Wait()
+
+		// can't continue until timestamp is in sequence, defer for now
+		return engine.ErrBackPoke
+	}
+
+	// semaphores!
+	// These shouldn't ever block an exit, since the graph should eventually
+	// converge causing their them to unlock. More interestingly, since they
+	// run in a DAG alphabetically, there is no way to permanently deadlock,
+	// assuming that resources individually don't ever block from finishing!
+	// The exception is that semaphores with a zero count will always block!
+	// TODO: Add a close mechanism to close/unblock zero count semaphores...
+	semas := res.MetaParams().Sema
+	if obj.Debug && len(semas) > 0 {
+		obj.Logf("%s: Sema: P(%s)", res, strings.Join(semas, ", "))
+	}
+	if err := obj.semaLock(semas); err != nil { // lock
+		// NOTE: in practice, this might not ever be truly necessary...
+		return fmt.Errorf("shutdown of semaphores")
+	}
+	defer obj.semaUnlock(semas) // unlock
+	if obj.Debug && len(semas) > 0 {
+		defer obj.Logf("%s: Sema: V(%s)", res, strings.Join(semas, ", "))
+	}
+
+	// sendrecv!
+	// connect any senders to receivers and detect if values changed
+	// this actually checks and sends into resource trees recursively...
+	if res, ok := vertex.(engine.RecvableRes); ok {
+		if obj.Debug {
+			obj.Logf("SendRecv: %s", res) // receiving here
+		}
+		if updated, err := SendRecv(res, nil); err != nil {
+			return errwrap.Wrapf(err, "could not SendRecv")
+		} else if len(updated) > 0 {
+			//for _, s := range graph.UpdatedStrings(updated) {
+			//	obj.Logf("SendRecv: %s", s)
+			//}
+			for r, m := range updated { // map[engine.RecvableRes]map[string]*engine.Send
+				v, ok := r.(pgraph.Vertex)
+				if !ok {
+					continue
+				}
+				_, stateExists := obj.state[v] // autogrouped children probably don't have a state
+				if !stateExists {
+					continue
+				}
+				for s, send := range m {
+					if !send.Changed {
+						continue
+					}
+					obj.Logf("Send/Recv: %v.%s -> %v.%s", send.Res, send.Key, r, s)
+					// if send.Changed == true, at least one was updated
+					// invalidate cache, mark as dirty
+					obj.state[v].setDirty()
+					//break // we might have more vertices now
+				}
+
+				// re-validate after we change any values
+				if err := engine.Validate(r); err != nil {
+					return errwrap.Wrapf(err, "failed Validate after SendRecv")
+				}
+			}
+		}
+	}
+
+	var ok = true
+	var applied = false              // did we run an apply?
+	var noop = res.MetaParams().Noop // lookup the noop value
+	var refresh bool
+	var checkOK bool
+	var err error
+
+	// lookup the refresh (notification) variable
+	refresh = obj.RefreshPending(vertex) // do i need to perform a refresh?
+	refreshableRes, isRefreshableRes := vertex.(engine.RefreshableRes)
+	if isRefreshableRes {
+		refreshableRes.SetRefresh(refresh) // tell the resource
+	}
+
+	// Check cached state, to skip CheckApply, but can't skip if refreshing!
+	// If the resource doesn't implement refresh, skip the refresh test.
+	// FIXME: if desired, check that we pass through refresh notifications!
+	if (!refresh || !isRefreshableRes) && obj.state[vertex].isStateOK.Load() { // mutex RLock/RUnlock
+		checkOK, err = true, nil
+
+	} else if noop && (refresh && isRefreshableRes) { // had a refresh to do w/ noop!
+		checkOK, err = false, nil // therefore the state is wrong
+
+	} else {
+		// run the CheckApply!
+		obj.Logf("%s: CheckApply(%t)", res, !noop)
+		// if this fails, don't UpdateTimestamp()
+		checkOK, err = res.CheckApply(ctx, !noop)
+		obj.Logf("%s: CheckApply(%t): Return(%t, %s)", res, !noop, checkOK, engineUtil.CleanError(err))
+	}
+
+	if checkOK && err != nil { // should never return this way
+		return fmt.Errorf("%s: resource programming error: CheckApply(%t): %t, %+v", res, !noop, checkOK, err)
+	}
+
+	if !checkOK { // something changed, restart timer
+		obj.state[vertex].cuid.ResetTimer() // activity!
+		if obj.Debug {
+			obj.Logf("%s: converger: reset timer", res)
+		}
+	}
+
+	// if CheckApply ran without noop and without error, state should be good
+	if !noop && err == nil { // aka !noop || checkOK
+		obj.state[vertex].tuid.StartTimer()
+		//obj.state[vertex].mutex.Lock()
+		obj.state[vertex].isStateOK.Store(true) // reset
+		//obj.state[vertex].mutex.Unlock()
+		if refresh {
+			obj.SetUpstreamRefresh(vertex, false) // refresh happened, clear the request
+			if isRefreshableRes {
+				refreshableRes.SetRefresh(false)
+			}
+		}
+	}
+
+	if !checkOK { // if state *was* not ok, we had to have apply'ed
+		if err != nil { // error during check or apply
+			ok = false
+		} else {
+			applied = true
+		}
+	}
+
+	// when noop is true we always want to update timestamp
+	if noop && err == nil {
+		ok = true
+	}
+
+	if ok {
+		// did we actually do work?
+		activity := applied
+		if noop {
+			activity = false // no we didn't do work...
+		}
+
+		if activity { // add refresh flag to downstream edges...
+			obj.SetDownstreamRefresh(vertex, true)
+		}
+
+		// poke! (should (must?) be sync)
+		wg := &sync.WaitGroup{}
+		// update this timestamp *before* we poke or the poked
+		// nodes might fail due to having a too old timestamp!
+		obj.state[vertex].mutex.Lock()                      // concurrent write start
+		obj.state[vertex].timestamp = time.Now().UnixNano() // update timestamp (race)
+		obj.state[vertex].mutex.Unlock()                    // concurrent write end
+		for _, v := range obj.graph.OutgoingGraphVertices(vertex) {
+			if !obj.OKTimestamp(v) {
+				// there is at least another one that will poke this...
+				continue
+			}
+
+			// If we're pausing (or exiting) then we can skip poking
+			// so that the graph doesn't go on running forever until
+			// it's completely done. This is an optional feature and
+			// we can select it via ^C on user exit or via the GAPI.
+			if obj.fastPause {
+				obj.Logf("%s: fast pausing, poke skipped", res)
+				continue
+			}
+
+			// poke each vertex individually, in parallel...
+			wg.Add(1)
+			go func(vv pgraph.Vertex) {
+				defer wg.Done()
+				obj.state[vv].Poke()
+			}(v)
+		}
+		wg.Wait()
+	}
+
+	return errwrap.Wrapf(err, "error during Process()")
+}
+
+// Worker is the common run frontend of the vertex. It handles all of the retry
+// and retry delay common code, and ultimately returns the final status of this
+// vertex execution. This function cannot be "re-run" for the same vertex. The
+// retry mechanism stuff happens inside of this. To actually "re-run" you need
+// to remove the vertex and build a new one. The engine guarantees that we do
+// not allow CheckApply to run while we are paused. That is enforced here.
+func (obj *Engine) Worker(vertex pgraph.Vertex) error {
+	res, isRes := vertex.(engine.Res)
+	if !isRes {
+		return fmt.Errorf("vertex is not a resource")
+	}
+
+	// bonus safety check
+	if res.MetaParams().Burst == 0 && !(res.MetaParams().Limit == rate.Inf) { // blocked
+		return fmt.Errorf("permanently limited (rate != Inf, burst = 0)")
+	}
+
+	// initialize or reinitialize the meta state for this resource uid
+	obj.mlock.Lock()
+	if _, exists := obj.metas[engine.PtrUID(res)]; !exists || res.MetaParams().Reset {
+		obj.metas[engine.PtrUID(res)] = &engine.MetaState{
+			CheckApplyRetry: res.MetaParams().Retry, // lookup the retry value
+		}
+	}
+	metas := obj.metas[engine.PtrUID(res)] // handle
+	obj.mlock.Unlock()
+
+	//defer close(obj.state[vertex].stopped) // done signal
+
+	obj.state[vertex].cuid = obj.Converger.Register()
+	obj.state[vertex].tuid = obj.Converger.Register()
+	// must wait for all users of the cuid to finish *before* we unregister!
+	// as a result, this defer happens *before* the below wait group Wait...
+	defer obj.state[vertex].cuid.Unregister()
+	defer obj.state[vertex].tuid.Unregister()
+
+	defer obj.state[vertex].wg.Wait() // this Worker is the last to exit!
+
+	obj.state[vertex].wg.Add(1)
+	go func() {
+		defer obj.state[vertex].wg.Done()
+		defer close(obj.state[vertex].eventsChan) // we close this on behalf of res
+
+		// This is a close reverse-multiplexer. If any of the channels
+		// close, then it will cause the doneCtx to cancel. That way,
+		// multiple different folks can send a close signal, without
+		// every worrying about duplicate channel close panics.
+		obj.state[vertex].wg.Add(1)
+		go func() {
+			defer obj.state[vertex].wg.Done()
+
+			// reverse-multiplexer: any close, causes *the* close!
+			select {
+			case <-obj.state[vertex].processDone:
+			case <-obj.state[vertex].watchDone:
+			case <-obj.state[vertex].limitDone:
+			case <-obj.state[vertex].retryDone:
+			case <-obj.state[vertex].removeDone:
+			case <-obj.state[vertex].eventsDone:
+			}
+
+			// the main "done" signal gets activated here!
+			obj.state[vertex].doneCtxCancel() // cancels doneCtx
+		}()
+
+		var err error
+		var retry = res.MetaParams().Retry // lookup the retry value
+		var delay uint64
+		for { // retry loop
+			// a retry-delay was requested, wait, but don't block events!
+			if delay > 0 {
+				errDelayExpired := engine.Error("delay exit")
+				err = func() error { // slim watch main loop
+					timer := time.NewTimer(time.Duration(delay) * time.Millisecond)
+					defer obj.state[vertex].init.Logf("the Watch delay expired!")
+					defer timer.Stop() // it's nice to cleanup
+					for {
+						select {
+						case <-timer.C: // the wait is over
+							return errDelayExpired // special
+
+						case <-obj.state[vertex].doneCtx.Done():
+							return nil
+						}
+					}
+				}()
+				if err == errDelayExpired {
+					delay = 0 // reset
+					continue
+				}
+			} else if interval := res.MetaParams().Poll; interval > 0 { // poll instead of watching :(
+				obj.state[vertex].cuid.StartTimer()
+				err = obj.state[vertex].poll(obj.state[vertex].doneCtx, interval)
+				obj.state[vertex].cuid.StopTimer() // clean up nicely
+			} else {
+				obj.state[vertex].cuid.StartTimer()
+				if obj.Debug {
+					obj.Logf("%s: Watch...", vertex)
+				}
+				err = res.Watch(obj.state[vertex].doneCtx) // run the watch normally
+				if obj.Debug {
+					if s := engineUtil.CleanError(err); err != nil {
+						obj.Logf("%s: Watch Error: %s", vertex, s)
+					} else {
+						obj.Logf("%s: Watch Exited...", vertex)
+					}
+				}
+				obj.state[vertex].cuid.StopTimer() // clean up nicely
+			}
+			if err == nil { // || err == engine.ErrClosed
+				return // exited cleanly, we're done
+			}
+			// we've got an error...
+			delay = res.MetaParams().Delay
+
+			if retry < 0 { // infinite retries
+				continue
+			}
+			if retry > 0 { // don't decrement past 0
+				retry--
+				obj.state[vertex].init.Logf("retrying Watch after %.4f seconds (%d left)", float64(delay)/1000, retry)
+				continue
+			}
+			//if retry == 0 { // optional
+			//	err = errwrap.Wrapf(err, "permanent watch error")
+			//}
+			break // break out of this and send the error
+		} // for retry loop
+
+		// this section sends an error...
+		// If the CheckApply loop exits and THEN the Watch fails with an
+		// error, then we'd be stuck here if exit signal didn't unblock!
+		select {
+		case obj.state[vertex].eventsChan <- errwrap.Wrapf(err, "watch failed"):
+			// send
+		}
+	}()
+
+	// If this exits cleanly, we must unblock the reverse-multiplexer.
+	// I think this additional close is unnecessary, but it's not harmful.
+	defer close(obj.state[vertex].eventsDone) // causes doneCtx to cancel
+	limiter := rate.NewLimiter(res.MetaParams().Limit, res.MetaParams().Burst)
+	var reserv *rate.Reservation
+	var reterr error
+	var failed bool // has Process permanently failed?
+	var closed bool // has the resumeSignal channel closed?
+Loop:
+	for { // process loop
+		// This is the main select where things happen and where we exit
+		// from. It's similar to the two "satellite" select's which we
+		// might spend some time in if we're retrying or rate limiting.
+		// This select is also the main event receiver and is also the
+		// only place where we read from the poke channel.
+		select {
+		case err, ok := <-obj.state[vertex].eventsChan: // read from watch channel
+			if !ok {
+				return reterr // we only return when chan closes
+			}
+			// If the Watch method exits with an error, then this
+			// channel will get that error propagated to it, which
+			// we then save so we can return it to the caller of us.
+			if err != nil {
+				failed = true
+				close(obj.state[vertex].watchDone)   // causes doneCtx to cancel
+				reterr = errwrap.Append(reterr, err) // permanent failure
+				continue
+			}
+			if obj.Debug {
+				obj.Logf("event received")
+			}
+			reserv = limiter.ReserveN(time.Now(), 1) // one event
+			// reserv.OK() seems to always be true here!
+
+		case _, ok := <-obj.state[vertex].pokeChan: // read from buffered poke channel
+			if !ok { // we never close it
+				panic("unexpected close of poke channel")
+			}
+			if obj.Debug {
+				obj.Logf("poke received")
+			}
+			reserv = nil // we didn't receive a real event here...
+
+		case _, ok := <-obj.state[vertex].pauseSignal: // one message
+			if !ok {
+				obj.state[vertex].pauseSignal = nil
+				continue // this is not a new pause message
+			}
+			// NOTE: If we allowed a doneCtx below to let us out
+			// of the resumeSignal wait, then we could loop around
+			// and run this again, causing a panic. Instead of this
+			// being made safe with a sync.Once, we instead run a
+			// close() call inside of the vertexRemoveFn function,
+			// which should unblock resumeSignal so we can shutdown.
+
+			// we are paused now, and waiting for resume or exit...
+			select {
+			case _, ok := <-obj.state[vertex].resumeSignal: // channel closes
+				if !ok {
+					closed = true
+				}
+				// resumed!
+				// pass through to allow a Process to try to run
+				// TODO: consider adding this fast pause here...
+				//if obj.fastPause {
+				//	obj.Logf("fast pausing on resume")
+				//	continue
+				//}
+			}
+		}
+
+		// drop redundant pokes
+		for len(obj.state[vertex].pokeChan) > 0 {
+			select {
+			case <-obj.state[vertex].pokeChan:
+			default:
+				// race, someone else read one!
+			}
+		}
+
+		// don't Process anymore if we've already failed or shutdown...
+		if failed || closed {
+			continue Loop
+		}
+
+		// limit delay
+		d := time.Duration(0)
+		if reserv != nil {
+			d = reserv.DelayFrom(time.Now())
+		}
+		if reserv != nil && d > 0 { // delay
+			obj.state[vertex].init.Logf("limited (rate: %v/sec, burst: %d, next: %dms)", res.MetaParams().Limit, res.MetaParams().Burst, d/time.Millisecond)
+			timer := time.NewTimer(time.Duration(d) * time.Millisecond)
+		LimitWait:
+			for {
+				// This "satellite" select doesn't need a poke
+				// channel because we're already in "event
+				// received" mode, and poke doesn't block.
+				select {
+				case <-timer.C: // the wait is over
+					break LimitWait
+
+				// consume other events while we're waiting...
+				case e, ok := <-obj.state[vertex].eventsChan: // read from watch channel
+					if !ok {
+						return reterr // we only return when chan closes
+					}
+					if e != nil {
+						failed = true
+						close(obj.state[vertex].limitDone) // causes doneCtx to cancel
+						reterr = errwrap.Append(reterr, e) // permanent failure
+						break LimitWait
+					}
+					if obj.Debug {
+						obj.Logf("event received in limit")
+					}
+					// TODO: does this get added in properly?
+					limiter.ReserveN(time.Now(), 1) // one event
+
+				// this pause/resume block is the same as the upper main one
+				case _, ok := <-obj.state[vertex].pauseSignal:
+					if !ok {
+						obj.state[vertex].pauseSignal = nil
+						break LimitWait
+					}
+					select {
+					case _, ok := <-obj.state[vertex].resumeSignal: // channel closes
+						if !ok {
+							closed = true
+						}
+						// resumed!
+					}
+				}
+			}
+			timer.Stop() // it's nice to cleanup
+			obj.state[vertex].init.Logf("rate limiting expired!")
+		}
+		// don't Process anymore if we've already failed or shutdown...
+		if failed || closed {
+			continue Loop
+		}
+		// end of limit delay
+
+		// retry...
+		var err error
+		//var retry = res.MetaParams().Retry // lookup the retry value
+		var delay uint64
+	RetryLoop:
+		for { // retry loop
+			if delay > 0 {
+				timer := time.NewTimer(time.Duration(delay) * time.Millisecond)
+			RetryWait:
+				for {
+					// This "satellite" select doesn't need
+					// a poke channel because we're already
+					// in "event received" mode, and poke
+					// doesn't block.
+					select {
+					case <-timer.C: // the wait is over
+						break RetryWait
+
+					// consume other events while we're waiting...
+					case e, ok := <-obj.state[vertex].eventsChan: // read from watch channel
+						if !ok {
+							return reterr // we only return when chan closes
+						}
+						if e != nil {
+							failed = true
+							close(obj.state[vertex].retryDone) // causes doneCtx to cancel
+							reterr = errwrap.Append(reterr, e) // permanent failure
+							break RetryWait
+						}
+						if obj.Debug {
+							obj.Logf("event received in retry")
+						}
+						// TODO: does this get added in properly?
+						limiter.ReserveN(time.Now(), 1) // one event
+
+					// this pause/resume block is the same as the upper main one
+					case _, ok := <-obj.state[vertex].pauseSignal:
+						if !ok {
+							obj.state[vertex].pauseSignal = nil
+							break RetryWait
+						}
+						select {
+						case _, ok := <-obj.state[vertex].resumeSignal: // channel closes
+							if !ok {
+								closed = true
+							}
+							// resumed!
+						}
+					}
+				}
+				timer.Stop() // it's nice to cleanup
+				delay = 0    // reset
+				obj.state[vertex].init.Logf("the CheckApply delay expired!")
+			}
+			// don't Process anymore if we've already failed or shutdown...
+			if failed || closed {
+				continue Loop
+			}
+
+			if obj.Debug {
+				obj.Logf("Process(%s)", vertex)
+			}
+			backPoke := false
+			err = obj.Process(obj.state[vertex].doneCtx, vertex)
+			if err == engine.ErrBackPoke {
+				backPoke = true
+				err = nil // for future code safety
+			}
+			if obj.Debug && backPoke {
+				obj.Logf("Process(%s): BackPoke!", vertex)
+			}
+			if obj.Debug && !backPoke {
+				obj.Logf("Process(%s): Return(%s)", vertex, engineUtil.CleanError(err))
+			}
+			if err == nil && !backPoke && res.MetaParams().RetryReset { // reset it on success!
+				metas.CheckApplyRetry = res.MetaParams().Retry // lookup the retry value
+			}
+			if err == nil || backPoke {
+				break RetryLoop
+			}
+			// we've got an error...
+			delay = res.MetaParams().Delay
+
+			if metas.CheckApplyRetry < 0 { // infinite retries
+				continue
+			}
+			if metas.CheckApplyRetry > 0 { // don't decrement past 0
+				metas.CheckApplyRetry--
+				obj.state[vertex].init.Logf(
+					"retrying CheckApply after %.4f seconds (%d left)",
+					float64(delay)/1000,
+					metas.CheckApplyRetry,
+				)
+				continue
+			}
+			//if metas.CheckApplyRetry == 0 { // optional
+			//	err = errwrap.Wrapf(err, "permanent process error")
+			//}
+
+			// It is important that we shutdown the Watch loop if
+			// this dies. If Process fails permanently, we ask it
+			// to exit right here... (It happens when we loop...)
+			failed = true
+			close(obj.state[vertex].processDone) // causes doneCtx to cancel
+			reterr = errwrap.Append(reterr, err) // permanent failure
+			continue
+
+		} // retry loop
+
+		// When this Process loop exits, it's because something has
+		// caused Watch() to shutdown (even if it's our permanent
+		// failure from Process), which caused this channel to close.
+		// On or more exit signals are possible, and more than one can
+		// happen simultaneously.
+
+	} // process loop
+
+	//return nil // unreachable
+}

engine/graph/autoedge.go

@@ -0,0 +1,42 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package graph
+
+import (
+	"github.com/purpleidea/mgmt/engine/graph/autoedge"
+)
+
+// AutoEdge adds the automatic edges to the graph.
+func (obj *Engine) AutoEdge() error {
+	logf := func(format string, v ...interface{}) {
+		obj.Logf("autoedge: "+format, v...)
+	}
+	return autoedge.AutoEdge(obj.nextGraph, obj.Debug, logf)
+}