Merge branch 'main' into release

# Conflicts:
#	.run/Run SQS Client.run.xml
#	README.md
#	build.settings
#	cmd/main.go
#	docker/entrypoint.sh
#	pubsub/listener.go

.github/workflows/codeql-analysis.yml

@@ -12,13 +12,8 @@
 name: "CodeQL"
 
 on:
-  push:
-    branches: [ "main" ]
   pull_request:
-    # The branches below must be a subset of the branches above
     branches: [ "main" ]
-  schedule:
-    - cron: '28 10 * * 2'
 
 jobs:
   analyze:

.run/Run All Tests.run.xml

@@ -1,17 +1,8 @@
 <!--
   ~ Copyright (c) 2022 AlertAvert.com.  All rights reserved.
   ~
-  ~ Licensed under the Apache License, Version 2.0 (the "License");
-  ~ you may not use this file except in compliance with the License.
-  ~ You may obtain a copy of the License at
-  ~
-  ~     http://www.apache.org/licenses/LICENSE-2.0
-  ~
-  ~ Unless required by applicable law or agreed to in writing, software
-  ~ distributed under the License is distributed on an "AS IS" BASIS,
-  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-  ~ See the License for the specific language governing permissions and
-  ~ limitations under the License.
+  ~ Licensed under the Apache License, Version 2.0
+  ~ http://www.apache.org/licenses/LICENSE-2.0
   ~
   ~ Author: Marco Massenzio ([email protected])
   -->

.run/Run SQS Client.run.xml

@@ -2,7 +2,7 @@
   <configuration default="false" name="Run SQS Client" type="GoApplicationRunConfiguration" factoryName="Go Application" editBeforeRun="true">
     <module name="statemachine" />
     <working_directory value="$PROJECT_DIR$" />
-    <parameters value="-endpoint http://localhost:4566 -q events -dest test.orders#25 -evt ship" />
+    <parameters value="-endpoint http://localhost:4566 -q events -dest test.orders#2 -evt accept" />
     <kind value="FILE" />
     <package value="github.com/massenz/go-statemachine/clients" />
     <directory value="$PROJECT_DIR$" />

.run/Run Server.run.xml

@@ -1,3 +1,12 @@
+<!--
+  ~ Copyright (c) 2022 AlertAvert.com.  All rights reserved.
+  ~
+  ~ Licensed under the Apache License, Version 2.0
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Author: Marco Massenzio ([email protected])
+  -->
+
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="Run Server" type="GoApplicationRunConfiguration" factoryName="Go Application">
     <module name="statemachine" />
@@ -13,4 +22,4 @@
     <filePath value="$PROJECT_DIR$/cmd/main.go" />
     <method v="2" />
   </configuration>
-</component>
+</component>

.run/Run gRPC Client.run.xml

@@ -1,3 +1,12 @@
+<!--
+  ~ Copyright (c) 2022 AlertAvert.com.  All rights reserved.
+  ~
+  ~ Licensed under the Apache License, Version 2.0
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Author: Marco Massenzio ([email protected])
+  -->
+
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="Run gRPC Client" type="GoApplicationRunConfiguration" factoryName="Go Application">
     <module name="statemachine" />
@@ -8,4 +17,4 @@
     <filePath value="$PROJECT_DIR$/clients/grpc_client.go|$PROJECT_DIR$/clients/orders.go" />
     <method v="2" />
   </configuration>
-</component>
+</component>

Makefile

@@ -20,40 +20,63 @@ all_go := $(shell for d in $(pkgs); do find $$d -name "*.go"; done)
 test_srcs := $(shell for d in $(pkgs); do find $$d -name "*_test.go"; done)
 srcs := $(filter-out $(test_srcs),$(all_go))
 
-# Builds the server
-#
+##@ General
+
+# The help target prints out all targets with their descriptions organized
+# beneath their categories. The categories are represented by '##@' and the
+# target descriptions by '##'. The awk commands is responsible for reading the
+# entire set of makefiles included in this invocation, looking for lines of the
+# file as xyz: ## something, and then pretty-format the target and help. Then,
+# if there's a line with ##@ something, that gets pretty-printed as a category.
+# More info on the usage of ANSI control characters for terminal formatting:
+# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
+# More info on the awk command:
+# http://linuxcommand.org/lc3_adv_awk.php
+
+.PHONY: help
+help: ## Display this help.
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+.PHONY: clean
+clean: ## Cleans up the binary, container image and other data
+	@rm -f $(out)
+	@docker-compose -f $(compose) down
+	@docker rmi $(shell docker images -q --filter=reference=$(image))
+
+.PHONY: build test container cov clean fmt
+fmt: ## Formats the Go source code using 'go fmt'
+	@go fmt $(pkgs) ./cmd ./clients
+
+##@ Development
 $(out): cmd/main.go $(srcs)
 	go build -ldflags "-X $(module)/server.Release=$(tag)" -o $(out) cmd/main.go
 	@chmod +x $(out)
 
-build: $(out)
+build: $(out) ## Builds the server
+
+test: $(srcs) $(test_srcs) services queues ## Runs all tests, starting services first, if required
+	ginkgo $(pkgs)
+
+cov: $(srcs) $(test_srcs)  ## Runs the Test Coverage target and opens a browser window with the coverage report
+	@go test -coverprofile=/tmp/cov.out $(pkgs)
+	@go tool cover -html=/tmp/cov.out
 
+##@ Container Management
 # Convenience targets to run locally containers and
 # setup the test environments.
 #
-# TODO: will be replaced once we adopt TestContainers
-# (see Issue # 26)
-services:
+.PHONY: container
+container: $(out) ## Builds the container image
+	docker build -f $(dockerfile) -t $(image):$(tag) .
+
+# TODO: will be replaced once we adopt TestContainers (#26)
+.PHONY: services
+services: ## Starts the Redis and LocalStack containers
 	@docker-compose -f $(compose) up -d
 
-queues:
-	@for queue in events notifications; do \
+.PHONY: queues
+queues: ## Creates the SQS Queues in LocalStack
+	@for queue in events notifications acks; do \
 		aws --no-cli-pager --endpoint-url=http://localhost:4566 \
 			--region us-west-2 \
  			sqs create-queue --queue-name $$queue; done >/dev/null
-
-test: $(srcs) $(test_srcs) services queues
-	ginkgo $(pkgs)
-
-container: $(out)
-	docker build -f $(dockerfile) -t $(image):$(tag) .
-
-# Runs test coverage and displays the results in browser
-cov: $(srcs) $(test_srcs)
-	@go test -coverprofile=/tmp/cov.out $(pkgs)
-	@go tool cover -html=/tmp/cov.out
-
-clean:
-	@rm -f $(out)
-	@docker-compose -f $(compose) down
-	@docker rmi $(shell docker images -q --filter=reference=$(image))

README.md

@@ -12,6 +12,8 @@ A basic implementation of a Finite State Machine in Go
 **The code is copyright (c) 2022 AlertAvert.com. All rights reserved**<br>
 The code is released under the Apache 2.0 License, see `LICENSE` for details.
 
+Fixes and additions are always welcome and warmly appreciated, please see the [Contributing](#contributing) section for some guidance.
+
 # Overview
 
 ## Design
@@ -451,10 +453,14 @@ Usage of build/bin/sm-server:
     	Max number of attempts for a recoverable error to be retried against the Redis cluster (default 3)
   -notifications string
     	The name of the notification topic in SQS to publish events' outcomes to; if not specified, no outcomes will be published
+  -acks string
+    	(Requires `notifications`) The name of the acks topic in SQS to publish events' outcomes to; if specified, Ok outcomes will be published to the acks topic and other (error) outcomes to the notification topic
   -redis string
     	URI for the Redis cluster (host:port)
   -cluster
-        Enables connecting to a Redis deployment in cluster mode
+        If set, allows connecting to a Redis instance with cluster-mode enabled
+  -notify-error-only
+        If set, only errors will be sent to notification topics
   -timeout duration
     	Timeout for Redis (as a Duration string, e.g. 1s, 20ms, etc.) (default 200ms)
   -trace
@@ -513,6 +519,11 @@ ENV ERRORS_Q=notifications
 ENV REDIS=redis
 ENV REDIS_PORT=6379
 ENV DEBUG=""
+
+# Optional settings for the server
+ENV ACKS="-acks acks"
+ENV CLUSTER="-cluster"
+ENV NOTIFY_ERRORS_ONLY="-notify-errors-only"
 ```
 
 Additionally, a valid `credentials` file will need to be mounted (using the `-v` flag) in the container if connecting to AWS (instead of LocalStack):
@@ -524,6 +535,39 @@ where the `[profile]` matches the value in `AWS_PROFILE`.
 
 # Contributing
 
-Please follow the Go Style enshrined in `go fmt` before submitting PRs, refer to actual [Issues](#), and provide sufficient testing (ideally, ensuring your code coverage is better than 80%).
+Please follow the Go Style enshrined in `go fmt` before submitting PRs, refer to actual [Issues](https://github.com/massenz/go-statemachine/issues), and provide sufficient testing (ideally, ensuring code coverage is better than 70%).
 
 We prefer you submit a PR directly from cloning this repository and creating a feature branch, rather than from a fork.
+
+If you are relatively new to this topic, there are a few issues labeled as [`Good First Issue`](https://github.com/massenz/go-statemachine/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), those are a good starting point.
+
+Please, always **squash and rebase** on `main`, we try to keep a relatively clean and linear commit history, and each PR should just be **one** commit with a descriptive title (see below).
+
+## Detailed Requirements to submit a PR
+
+1. make sure the Issue you are trying to address is referenced appropriately in the PR Title:
+
+```
+[#34] Implements gRPC API to update/retrieve Event outcomes
+```
+
+2. prior to submitting the PR, make sure that the code is properly formatted and tested:
+
+```
+make fmt && make test
+```
+
+3. if this is a breaking change, or a significant change to the API or behavior, please update the [README](README.md) accordingly.
+
+## Guidelines to be A Good Contributor
+
+Provide enough detail of your changes in the PR comments and make it easy for reviewers:
+
+* if your code contains several lines of "commented out dead code" make sure that you clearly explain why this is so with a `TODO` and an explanation of why are you leaving dead code around (remember, we are using `git` here, there is no such thing "in case we forget" - `git` **never** forgets)
+* try and be consistent with the rest of the code base and, specifically, the code around the changes you are implementing
+* be consistent with the `import` format and sequence: if in doubt, again, look at the existing code and be **consistent**
+* make sure the new code is **covered by unit tests**, use `make cov` to check coverage % and view lines covered in the browser
+* try and adopt "The Boyscout Rule": leave the campsite cleaner than you found it -- in other words, adding tests, fixing typos, fixing **minor** issues is always **greatly** appreciated
+* conversely, try and keep the PR focused on one topic/issue/change, and one only: we'd rather review 2 PRs, than try and disentangle the two unrelated issues you're trying to address
+
+If in doubt, look at the existing code, or feel free to ask in the PR's comments - we don't bite :-)