From d6beb81938a99fcc6003a64b30c66d8b86a91ba1 Mon Sep 17 00:00:00 2001
From: Piotr Icikowski <piotrekicikowski@gmail.com>
Date: Fri, 1 Mar 2024 23:43:53 +0100
Subject: [PATCH] docs(kubeprobes): update README

---
 README.md | 56 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 44 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 4650d02..750af72 100644
--- a/README.md
+++ b/README.md
@@ -10,19 +10,23 @@ go get -u pkg.icikowski.pl/kubeprobes
 
 ## Usage
 
-The package provides `kubeprobes.New` function which returns a probes handler compliant with `http.Handler` interface.
+The package provides `kubeprobes.New` function which returns a probes handler of type `kubeprobes.Kubeprobes`, which is compliant with `http.Handler` interface.
 
 The handler serves two endpoints, which are used to implement liveness and readiness probes by returning either `200` (healthy) or `503` (unhealthy) status:
 
 - `/live` - endpoint for liveness probe;
 - `/ready` - endpoint for readiness probe.
 
-Accessing any other endpoint will return `404` status. In order to provide maximum performance, no body is ever returned.
+Default paths can be overriden with options described below. Accessing any other endpoint will return `404` status. In order to provide maximum performance, no body is ever returned.
 
-The `kubeprobes.New` function accepts following options-applying functions as arguments:
+The `kubeprobes.New` function accepts following options as arguments:
 
-- `kubeprobes.WithLivenessProbes(/* ... */)` - adds particular [probes](#probes) to the list of liveness probes;
-- `kubeprobes.WithReadinessProbes(/* ... */)` - adds particular [probes](#probes) to the list of readiness probes.
+- `kubeprobes.WithLivenessProbes(...)` - adds particular [probe functions](#probe-functions) to the list of liveness probes;
+- `kubeprobes.WithLivenessStatefulProbes(...)` - adds particular [`StatefulProbe`s](#stateful-probes) to the list of liveness probes;
+- `kubeprobes.WithLivenessPath("/some/liveness/path")` - sets liveness probe path to given path (default is `/live`);
+- `kubeprobes.WithReadinessProbes(...)` - adds particular [probe functions](#probe-functions) to the list of readiness probes;
+- `kubeprobes.WithReadinessStatefulProbes(...)` - adds particular [`StatefulProbe`s](#stateful-probes) to the list of readiness probes;
+- `kubeprobes.WithReadinessPath("/some/readiness/path")` - sets readiness probe path to given path (default is `/ready`).
 
 ## Probes
 
@@ -47,7 +51,7 @@ someOtherProbe := func() error {
 } 
 
 // Use functions in probes handler
-kp := kubeprobes.New(
+kp, _ := kubeprobes.New(
     kubeprobes.WithLivenessProbes(someOtherProbe),
     kubeprobes.WithReadinessProbes(someProbe),
 )
@@ -63,24 +67,52 @@ someProbe := kubeprobes.NewStatefulProbe()
 someOtherProbe := kubeprobes.NewStatefulProbe()
 
 // Use it in probes handler
-kp := kubeprobes.New(
-    kubeprobes.WithLivenessProbes(someProbe.GetProbeFunction()),
-    kubeprobes.WithReadinessProbes(someOtherProbe.GetProbeFunction()),
+kp, _ := kubeprobes.New(
+    kubeprobes.WithLivenessStatefulProbes(someProbe),
+    kubeprobes.WithReadinessStatefulProbes(someOtherProbe),
 )
 ```
 
+## Direct handler access
+
+It is possible to fetch `http.Handler`s for liveness & readiness probes from `kubeprobes.Kubeprobes` instance as follows:
+
+```go
+kp, _ := kubeprobes.New(
+    // ...
+)
+
+livenessHandler := kp.GetLivenessHandler()
+readinessHandler := kp.GetReadinessHandler()
+```
+
+Those handler can be used for manually mounting them on other servers/routers/muxes (eg. `go-chi/chi`, `gorilla/mux`, `http`'s `ServeMux` etc.). 
+
 ## Example usage
 
 ```go
+// Create probe functions
+appProbe := func() error {
+    // Some logic for checking app status
+    return nil
+}
+
 // Create stateful probes
 live := kubeprobes.NewStatefulProbe() 
 ready := kubeprobes.NewStatefulProbe()
 
 // Prepare handler
-kp := kubeprobes.New(
-    kubeprobes.WithLivenessProbes(live.GetProbeFunction()),
-    kubeprobes.WithReadinessProbes(ready.GetProbeFunction()),
+kp, err := kubeprobes.New(
+    kubeprobes.WithLivenessStatefulProbes(live),
+    kubeprobes.WithReadinessStatefulProbes(ready),
+    kubeprobes.WithReadinessProbes(appProbe),
+    kubeprobes.WithLivenessPath("/livez"),
+    kubeprobes.WithReadinessPath("/readyz"),
 )
+if err != nil {
+    // Kubeprobes object is validated for invalid or conflicting paths! ;)
+    panic(err)
+}
 
 // Start the probes server
 probes := &http.Server{