Create ci.yml

.devcontainer/devcontainer.json

@@ -1,9 +1,21 @@
 {
+	"name": "devicecode-lua",
 	"build": {
 		"dockerfile": "Dockerfile"
-		// [Optional] You can use build args to set options. e.g. 'VARIANT' below affects the image in the Dockerfile
-		// "args": { "VARIANT": "buster" }
 	},
-    "remoteUser": "vscode",
-    "postCreateCommand": "bash .devcontainer/postCreateCommand.sh"
-}
+	"remoteUser": "vscode",
+	"postCreateCommand": "bash .devcontainer/postCreateCommand.sh",
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-azuretools.vscode-docker",
+				"ms-vscode-remote.remote-containers",
+				"waderyan.gitblame",
+				"sumneko.lua",
+				"rog2.luacheck",
+				"tomblind.local-lua-debugger-vscode",
+				"bierner.markdown-mermaid"
+			]
+		}
+	}
+}

.devcontainer/postCreateCommand.sh

@@ -14,6 +14,7 @@ sudo luarocks install bit32
 sudo luarocks install cqueues
 sudo luarocks install http
 sudo luarocks install luaposix
+sudo luarocks install luacheck
 
 # install cffi-lua
 
@@ -29,19 +30,9 @@ sudo ninja all
 sudo ninja test
 sudo cp cffi.so /usr/local/lib/lua/5.1/cffi.so
 
-# install go
-cd /tmp
-
-arch=$(uname -m)
+# pre-commit for CI
 
-if [ "$arch" = "aarch64" ]
-then
-   wget https://go.dev/dl/go1.21.0.linux-arm64.tar.gz
-else
-   wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
-fi
-sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.21.0.linux*.tar.gz
-echo "export PATH=$PATH:/usr/local/go/bin" >> $HOME/.profile
-echo "export PATH=$PATH:/usr/local/go/bin" >> $HOME/.bashrc
+sudo apt-get install -y pre-commit
+pre-commit install
 
-exit 0
+exit 0

.env

@@ -0,0 +1,3 @@
+FIBERS_VER=main
+TRIE_VER=main
+BUS_VER=main

.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: devicecode-ci
+
+on:
+  pull_request:
+    branches:
+      - main
+      - dev
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4.2.2
+        with:
+          submodules: recursive
+          token: ${{ secrets.DEVICECODE_TOKEN }}
+
+      - name: install-luajit
+        uses: leafo/gh-actions-lua@v10.0.0
+        with:
+          luaVersion: "luajit-openresty"
+
+      - name: install-luarocks
+        uses: leafo/gh-actions-luarocks@v4.3.0
+
+      - name: install-luacheck
+        run: luarocks install luacheck
+
+      - name: install-bit32
+        run: luarocks install bit32
+
+      - name: install-cqueues
+        run: luarocks install cqueues
+
+      - name: install-http
+        run: luarocks install http
+
+      - name: install-luaposix
+        run: luarocks install luaposix
+
+      - name: setup-env
+        run: make env
+
+      - name: run-lint
+        run: make lint
+
+      - name: run-tests
+        if: always()
+        run: make test-all

.gitmodules

@@ -0,0 +1,9 @@
+[submodule "src/lua-fibers"]
+	path = src/lua-fibers
+	url = https://github.com/jangala-dev/lua-fibers.git
+[submodule "src/lua-trie"]
+	path = src/lua-trie
+	url = https://github.com/jangala-dev/lua-trie.git
+[submodule "src/lua-bus"]
+	path = src/lua-bus
+	url = https://github.com/jangala-dev/lua-bus.git

.luacheckrc

@@ -0,0 +1,4 @@
+std = "lua51+luajit"
+ignore = {
+  "212/self"
+}

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: local
+    hooks:
+      - id: dc-pre-commit
+        name: dc-pre-commit
+        entry: ./pre-commit.sh
+        language: system

.vscode/extensions.json

@@ -0,0 +1,11 @@
+{
+    "recommendations": [
+      "ms-azuretools.vscode-docker",
+      "ms-vscode-remote.remote-containers",
+      "waderyan.gitblame",
+      "sumneko.lua",
+      "rog2.luacheck",
+      "tomblind.local-lua-debugger-vscode",
+      "bierner.markdown-mermaid"
+    ]
+  }

.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+    "editor.tabSize": 2,
+    "editor.indentSize": "tabSize",
+    "editor.insertSpaces": true,
+    "editor.formatOnSave": true,
+    "editor.formatOnSaveMode": "modifications",
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "never"
+    },
+    "files.insertFinalNewline": true,
+    "files.trimTrailingWhitespace": true,
+    "json.schemas": [],
+    "terminal.integrated.defaultProfile.linux": "bash",
+    "[lua]": {
+      "editor.tabSize": 4
+    },
+  }

Makefile

@@ -0,0 +1,85 @@
+# Variables
+include .env
+SRC_DIR := src
+BUILD_DIR := build
+TEST_DIR := tests
+LINTER := luacheck
+
+# Default target
+.PHONY: all
+all: env test-all build lint
+
+# Build: Moves source files and removes and testing from submodules
+.PHONY: build
+build:
+	@echo "Building the project..."
+	@mkdir -p $(BUILD_DIR)
+	@cp -r $(SRC_DIR)/* $(BUILD_DIR)/
+	@cp $(BUILD_DIR)/lua-bus/src/* $(BUILD_DIR)
+	@rm -r $(BUILD_DIR)/lua-bus
+	@cp -r $(BUILD_DIR)/lua-fibers/fibers $(BUILD_DIR)/fibers
+	@rm -r $(BUILD_DIR)/lua-fibers
+	@cp $(BUILD_DIR)/lua-trie/src/* $(BUILD_DIR)
+	@rm -r $(BUILD_DIR)/lua-trie
+	@echo "Build complete."
+
+# Test: Run the project's test suite
+.PHONY: test
+test:
+	@echo "Running project tests..."
+	@cd $(TEST_DIR) && luajit test.lua
+	@echo "Tests completed."
+
+# Test-All: Run the project's and submodule's test suite
+.PHONY: test-all
+test-all:
+	@echo "Running all tests..."
+# Devicecode tests
+	@cd $(TEST_DIR) && luajit test.lua
+# Fiber tests
+	@cd $(SRC_DIR)/lua-fibers/tests && luajit test.lua
+# Trie tests
+	@cd $(SRC_DIR)/lua-trie/tests && luajit test.lua
+# Bus tests (require movement of fiber and trie then cleanup)
+	@cp -r $(SRC_DIR)/lua-fibers/fibers $(SRC_DIR)/lua-bus/src
+	@cp -r $(SRC_DIR)/lua-trie/src/* $(SRC_DIR)/lua-bus/src
+	@cd $(SRC_DIR)/lua-bus/tests && luajit test.lua
+	@rm -rf $(SRC_DIR)/lua-bus/src/fibers
+	@rm -rf $(SRC_DIR)/lua-bus/src/trie.lua
+	@echo "Tests completed."
+
+# Env: Initialize environment and update git submodules
+.PHONY: env
+env:
+	@echo "Updating git submodules..."
+	@git submodule update --init --recursive
+	@cd $(SRC_DIR)/lua-fibers && git checkout $(FIBERS_VER)
+	@cd $(SRC_DIR)/lua-trie && git checkout $(TRIE_VER)
+	@cd $(SRC_DIR)/lua-bus && git checkout $(BUS_VER)
+	@echo "Git submodules updated."
+
+# Lint: Run the linter to check code quality
+.PHONY: lint
+lint:
+	@echo "Running linter..."
+	@$(LINTER) $(SRC_DIR) $(TEST_DIR)
+	@echo "Linting complete."
+
+# Clean: Remove build artifacts
+.PHONY: clean
+clean:
+	@echo "Cleaning build artifacts..."
+	@rm -rf $(BUILD_DIR)
+	@echo "Clean complete."
+
+# Help: Display available targets
+help:
+	@echo "Available targets:"
+	@echo "all          - Build, test, lint, and update submodules"
+	@echo "build        - Build the project (removes testing code and documentation)"
+	@echo "test         - Run project test suite"
+	@echo "test-all     - Run project and submodules test suite"
+	@echo "env          - Update and initialize git submodules"
+	@echo "lint         - Run the code linter"
+	@echo "clean        - Remove build artifacts"
+	@echo "help         - Display this help message"

README.md

@@ -1,2 +1,34 @@
 This repository contains the Lua version of [Jangala's](https://www.janga.la) `devicecode`, the
 program that powers our Big Box and Get Box devices.
+
+# Using make script
+SRC_DIR, TEST_DIR and BUILD_DIR are all optional values
+## Initialise dev environment
+Before testing or building the code all submodules need to be loaded in. You can select
+the version of each submodule in `.env`.
+```
+make env SRC_DIR=<src>
+```
+
+## Build devicecode
+Building devicecode creates a folder with only required source files and restructures the submodules
+to make a simpler file structure.
+```
+make build SRC_DIR=<src> BUILD_DIR=<build>
+```
+
+## Test devicecode
+Devicecode and it's submodules can be tested, to test devicecode only
+```
+make test TEST_DIR=<tests>
+```
+to test devicecode and the submodules
+```
+make test-all TEST_DIR=<tests> SRC_DIR=<src>
+```
+
+## Linter
+To run the linter
+```
+make lint SRC_DIR=<src> TEST_DIR=<tests>
+```

pre-commit.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+
+make env
+make lint
+
+ret=$?
+if [ $ret -ne 0 ]; then
+	exit $ret
+fi
+
+make test
+ret=$?
+if [ $ret -ne 0 ]; then
+	exit $ret
+fi
+
+exit 0

sprint-docs/service.md

@@ -0,0 +1,69 @@
+# Service structure
+## service spawning
+A service is created using service.spawn() which will follow the general form
+- Publish service active under `<service_name>/health`
+- Run service start function with arguments of bus connection and context (start function should be non-blocking)
+- Create a shutdown fiber
+- Shutdown fiber will 
+    - wait for a shutdown message on `<service_name>/control/shutdown`
+    - check all fibers' state on `<service_name>/health/fibers/+`
+    - track which fibers are not showing 'disabled' state yet
+    - once all fibers are showing disabled it will publish service state disabled and close
+
+## fiber spawning
+A service fiber is a fiber that is spawned with tracking features, spawning follows the steps
+- Publish 'fiber init' under `<service_name>/health/fibers/<fiber_name>`
+- create fiber and pass context with cancel and values fiber_name and service_name
+- when fiber spins up 
+    - publish 'fiber active'
+    - run the given function with ctx as argument (this function should be blocking)
+    - when given function returns, publish 'fiber disabled'
+
+# How to use
+## Spawn a service
+```lua
+service.spawn(service_obj, bus_connection, context)
+```
+
+## Spawn a service fiber
+```lua
+service.spawn(name, bus_connection, context, function (fiber_context)
+    -- do stuff
+end
+)
+```
+
+# Example
+```lua
+local service = require "service"
+local bus_mod = require "bus"
+local context = require "fibers.context"
+local op = require "fibers.op"
+local sleep = require "fibers.sleep"
+
+-- This is a dummy service
+local dummy_service = {}
+dummy_service.__index = dummy_service
+dummy_service.name = 'dummy_service'
+
+-- The start function should be non-blocking
+function dummy_service:start(bus_conn, ctx)
+    service.spawn_fiber('log-fiber', bus_conn, ctx, function (fib_ctx)
+        while not fib_ctx:err() do
+            print('fiber active')
+            op.choice(
+                sleep.sleep_op(1),
+                fib_ctx:done_op()
+            ):perform()
+        end
+    end)
+end
+
+local ctx = context.with_cancel(context.background)
+local bus = bus_mod.new({q_len=10, m_wild='#', s_wild='+', sep="/"})
+
+service.spawn(dummy_service, bus, ctx)
+
+sleep.sleep(5)
+ctx:cancel('shutdown')
+```