Better Kubernetes readiness check. (#42)

Author: ioquatix

bake/async/container/notify/log.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+def initialize(...)
+	super
+	
+	require "async/container/notify/log"
+end
+
+# Check if the log file exists and the service is ready.
+# @parameter path [String] The path to the notification log file, uses the `NOTIFY_LOG` environment variable if not provided.
+def ready?(path: Async::Container::Notify::Log.path)
+	if File.exist?(path)
+		File.foreach(path) do |line|
+			message = JSON.parse(line)
+			if message["ready"] == true
+				$stderr.puts "Service is ready: #{line}"
+				return true
+			end
+		end
+		
+		raise "Service is not ready yet."
+	else
+		raise "Notification log file does not exist at #{path}"
+	end
+end

guides/getting-started/readme.md

@@ -85,25 +85,3 @@ controller.run
 `SIGKILL` is the kill signal. The only behavior is to kill the process, immediately. As the process cannot catch the signal, it cannot cleanup, and thus this is a signal of last resort.
 
 `SIGSTOP` is the pause signal. The only behavior is to pause the process; the signal cannot be caught or ignored. The shell uses pausing (and its counterpart, resuming via `SIGCONT`) to implement job control.
-
-## Integration
-
-### systemd
-
-Install a template file into `/etc/systemd/system/`:
-
-```
-# my-daemon.service
-[Unit]
-Description=My Daemon
-AssertPathExists=/srv/
-
-[Service]
-Type=notify
-WorkingDirectory=/srv/my-daemon
-ExecStart=bundle exec my-daemon
-Nice=5
-
-[Install]
-WantedBy=multi-user.target
-```

guides/kubernetes-integration/readme.md

@@ -0,0 +1,39 @@
+# Kubernetes Integration
+
+This guide explains how to use `async-container` with Kubernetes to manage your application as a containerized service.
+
+## Deployment Configuration
+
+Create a deployment configuration file for your application:
+
+```yaml
+# my-app-deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-app
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: my-app
+  template:
+    metadata:
+      labels:
+        app: my-app
+    spec:
+      containers:
+        - name: my-app
+          image: my-app-image:latest
+          env:
+            - name: NOTIFY_LOG
+              value: "/tmp/notify.log"
+          ports:
+            - containerPort: 3000
+          readinessProbe:
+            exec:
+              command: ["bundle", "exec", "bake", "async:container:notify:log:ready?"]
+            initialDelaySeconds: 5
+            periodSeconds: 5
+            failureThreshold: 12
+```

guides/links.yaml

@@ -0,0 +1,8 @@
+getting-started:
+  order: 1
+systemd-integration:
+  order: 2
+kubernetes-integration:
+  order: 3
+docker-integration:
+  order: 4

guides/systemd-integration/readme.md

@@ -0,0 +1,22 @@
+# Systemd Integration
+
+This guide explains how to use `async-container` with systemd to manage your application as a service.
+
+## Service File
+
+Install a template file into `/etc/systemd/system/`:
+
+```
+# my-daemon.service
+[Unit]
+Description=My Daemon
+
+[Service]
+Type=notify
+ExecStart=bundle exec my-daemon
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Ensure `Type=notify` is set, so that the service can notify systemd when it is ready.

lib/async/container/forked.rb

@@ -189,6 +189,7 @@ def inspect
 					"\#<#{self.class} name=#{@name.inspect} status=#{@status.inspect} pid=#{@pid.inspect}>"
 				end
 
+				# @returns [String] A string representation of the process.
 				alias to_s inspect
 
 				# Invoke {#terminate!} and then {#wait} for the child process to exit.

lib/async/container/notify/log.rb

@@ -14,9 +14,16 @@ class Log < Client
 				# The name of the environment variable which contains the path to the notification socket.
 				NOTIFY_LOG = "NOTIFY_LOG"
 
+				# @returns [String] The path to the notification log file.
+				# @parameter environment [Hash] The environment variables, defaults to `ENV`.
+				def self.path(environment = ENV)
+					environment[NOTIFY_LOG]
+				end
+				
 				# Open a notification client attached to the current {NOTIFY_LOG} if possible.
+				# @parameter environment [Hash] The environment variables, defaults to `ENV`.
 				def self.open!(environment = ENV)
-					if path = environment.delete(NOTIFY_LOG)
+					if path = self.path(environment)
 						self.new(path)
 					end
 				end

lib/async/container/notify/pipe.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 # Copyright, 2020, by Juan Antonio Martín Lucas.
 
 require_relative "client"

releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## Unreleased
+
+  - Introduce `async:container:notify:log:ready?` task for detecting process readiness.
+
 ## v0.24.0
 
   - Add support for health check failure metrics.

test/async/container/hybrid.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require "async/container/hybrid"
 require "async/container/best"