Initial commit

.circleci/config.yml

@@ -0,0 +1,24 @@
+version: 2.1
+
+orbs:
+  ta-go: travelaudience/[email protected]
+
+executors:
+  golang-executor:
+    docker:
+    - image: cimg/go:1.19
+    environment:
+      GO111MODULE: "on"
+
+workflows:
+  build_and_test:
+    jobs:
+
+    - ta-go/checks:
+        name: check
+        exec: golang-executor
+        run-static-analysis: true
+
+    - ta-go/test_and_coverage:
+        name: test
+        exec: golang-executor

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# travel audience Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+### Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [email protected]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,16 @@
+<!--- STOP! Before you open an issue please search this repository's issues to see if it has already been reported. This helps reduce duplicate issues from being created. -->
+
+### Expected Behaviour
+
+### Actual Behaviour
+
+### Steps to Reproduce
+
+
+### Optional additional info:
+
+#### Platform and Version
+
+#### Sample Code that illustrates the problem
+
+#### Logs taken while reproducing problem

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+<!--  Thanks for sending a pull request!  Here are some tips for you:
+If this PR closes another issue, add 'closes #<issue number>' somewhere in the PR summary. GitHub will automatically close that issue when this PR gets merged. Alternatively, adding 'refs #<issue number>' will not close the issue, but help provide the reviewer more context.-->
+
+**What this PR does / why we need it**:
+
+**Special notes for your reviewer**:
+
+**If applicable**:
+- [ ] this PR contains documentation
+- [ ] this PR contains unit tests
+- [ ] this PR has been tested for backwards compatibility

CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Thanks for choosing to contribute!
+
+The following are a set of guidelines to follow when contributing to this project.
+
+## Have A Question?
+
+Start by filing an issue. The existing committers on this project work to reach
+consensus around project direction and issue solutions within issue threads
+(when appropriate).
+
+## How to Contribute Code
+
+1. Fork the repo, develop and test your code changes.
+1. Submit a pull request.
+
+Lastly, please follow the [pull request template](.github/PULL_REQUEST_TEMPLATE.md) when
+submitting a pull request!
+
+#### Documentation PRs
+
+Documentation PRs will follow the same lifecycle as other PRs. They should also be labeled with the
+`docs` label. For documentation, special attention will be paid to spelling, grammar, and clarity
+(whereas those things don't matter *as* much for comments in code).
+
+<!-- ## Security Issues
+
+Security issues shouldn't be reported on this issue tracker. Instead, please email a report to
+[[email protected]](mailto:[email protected]). This will give
+us a chance to try to fix the issue before it is exploited in the wild.
+ -->
+
+## Code Of Conduct
+
+This project adheres to the travel audience [code of conduct](.github/CODE_OF_CONDUCT.md). By participating,
+you are expected to uphold this code. Please report unacceptable behavior to
+[[email protected]](mailto:[email protected]).

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+© Copyright 2023 travel audience. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,17 @@
-# go-nested
-Nested services for Go
+# Nested Services
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/travelaudience/go-nested.svg)](https://pkg.go.dev/github.com/travelaudience/go-nested)
+[![CircleCI](https://circleci.com/gh/travelaudience/go-nested.svg?style=svg)](https://circleci.com/gh/travelaudience/go-nested)
+
+**go-nested** provides a simple library to simplify implementing nested services.
+
+A nested service is a service that runs in the background, independently of the main program, and exposes an API
+for communication with the main program or other services.  It functions much like a microservice, except that it
+runs on the same machine and is compiled into the same binary.
+
+A typical example of a nested service would be a caching layer, where the cache needs to be refreshed at some
+regular interval an some external source.  The nested service abstracts away the logic of maintaining the cache,
+exposing only an API to read from it.
+
+This library provides a simple mechanism for the main program to monitor the nested service and take appropriate
+action when the nested service is in an error state.

collection.go

@@ -0,0 +1,125 @@
+package nested
+
+import (
+	"math/rand"
+	"strconv"
+	"sync"
+)
+
+// A Collection monitors multiple services and keeps track of the overall state.  The overall state is defined as:
+//   - Ready if all of the services are ready.
+//   - Stopped if ANY of the services are stopped.
+//   - Not Ready otherwise.
+//
+// A Collection implements the Service interface but does not set the error states.
+//
+// Services to be monitored are added using the Add() method.  Services cannot be removed once added.
+//
+// An empty Collection is ready to use and in the Not Ready state.  A Collection must not be copied after first use.
+type Collection struct {
+	Monitor
+	sync.Mutex
+	services []Service
+	id       string
+	updates  chan Notification
+}
+
+// Verifies that a Monitor implements the Service interface.
+var _ Service = &Collection{}
+
+// Add adds a service to be monitored.  Panics if the service has already been added.
+func (c *Collection) Add(s Service) {
+	c.Lock()
+	defer c.Unlock()
+
+	// Initialize the update channel if this is the first service to be added.
+	if c.updates == nil {
+		c.updates = make(chan Notification)
+		go func() {
+			for range c.updates {
+				c.Monitor.SetState(c.getOverallState(), nil)
+			}
+		}()
+		// Using the same ID to subscribe to all monitored services means that Subscribe will panic below if a service
+		// is added twice.
+		c.id = "collection-" + strconv.Itoa(rand.Int())
+	}
+
+	c.services = append(c.services, s)
+	s.Subscribe(c.id, c.updates)
+}
+
+// StateCount returns the number of monitored services currently in the given state.
+func (c *Collection) StateCount(state State) int {
+	c.Lock()
+	defer c.Unlock()
+
+	var n int
+	for _, service := range c.services {
+		if s, _ := service.GetState(); s == state {
+			n++
+		}
+	}
+	return n
+}
+
+// Stop stops the collection and all monitored services and releases all of the resources.  Neither the collection nor
+// any of the services should be used after calling stop.
+func (c *Collection) Stop() {
+
+	// Start stopping all of the member services, and then release the lock.
+	u := func() chan Notification {
+
+		// Initialize the wait group first so that wg.Wait() runs after the lock is released.  That way, if we block
+		// on any of the Stop() calls, we do so without holding the lock.
+		wg := sync.WaitGroup{}
+		defer wg.Wait()
+
+		c.Lock()
+		defer c.Unlock()
+
+		wg.Add(len(c.services))
+		for _, service := range c.services {
+			// Unsubscribe first so that we can close the notifications channel.  Note that a side effect of
+			// unsubscribing here is that we need to explicitly set the monitor to stopped when we're done.
+			service.Unsubscribe(c.id)
+			go func(s Service) {
+				s.Stop()
+				wg.Done()
+			}(service)
+		}
+		c.services = nil
+
+		// Return the update channel so that we don't have to grab the lock again to get it.
+		return c.updates
+	}()
+
+	// Close the update channel to release the goroutine in Add() above.  If u is nil, that means that this collection
+	// hasn't been used, which is unexpected but not our concern.
+	if u != nil {
+		close(u)
+	}
+
+	// Need to explicitly set the monitor to stopped, since we unsubscribed already above.
+	c.Monitor.Stop()
+}
+
+// getOverallState computes the overall state of the collection: ready if all of the services are ready, stopped
+// if any of the services are stopped, and not ready otherwise.  getOverallState should not be called on an empty
+// collection, as it will give the incorrect state.
+func (c *Collection) getOverallState() State {
+	c.Lock()
+	defer c.Unlock()
+
+	we := State(Ready)
+	for _, service := range c.services {
+		state, _ := service.GetState()
+		switch state {
+		case Stopped:
+			return Stopped
+		case NotReady:
+			we = NotReady
+		}
+	}
+	return we
+}