Merge pull request #3 from LumeWeb/refactor/env-only-config-debug-logging

refactor: env-only config, remove Caddyfile directive, add debug logging

Author: pcfreak30

README.md

@@ -5,103 +5,50 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Tests](https://img.shields.io/github/actions/workflow/status/LumeWeb/caddy-plugin-cert-webhook/test.yml?branch=main&label=Tests)](https://github.com/LumeWeb/caddy-plugin-cert-webhook/actions)
 
-A Caddy v2 plugin that hooks into certificate lifecycle events and sends webhooks to a central portal service for real-time SSL certificate status tracking.
+A Caddy v2 app that hooks into certificate lifecycle events and reports SSL status to a portal service.
 
 ## Features
 
-- Subscribes to Caddy TLS certificate events (`cert_obtained`, `cert_renewed`, `cert_expired`)
-- Sends webhooks to portal endpoint with `X-Gateway-Secret` authentication
-- Maps Caddy events to portal SSL statuses (`pending`, `issuing`, `ready`, `failed`)
-- Async webhook delivery with exponential backoff retry for transient failures
-- Non-blocking delivery to avoid disrupting certificate operations
+- Subscribes to Caddy TLS events (`cert_obtained`, `cert_renewed`, `cert_expired`)
+- Reports status to portal via SDK (`ready` or `failed`)
+- Async delivery with concurrency limiting (100 concurrent)
+- Debug logging via Caddy's `{ debug }` global option
 
 ## Installation
 
-Build Caddy with this plugin using [xcaddy](https://github.com/caddyserver/xcaddy):
-
 ```bash
 xcaddy build --with github.com/LumeWeb/caddy-plugin-cert-webhook
 ```
 
-## Quick Start
-
-```caddyfile
-{
-    order cert_webhook before file_server
-}
-
-example.com {
-    tls {
-        cert_webhook {
-            portal_url https://portal.example.com
-        }
-    }
-}
-```
-
-Set environment variables:
-
-```bash
-export PORTAL_URL=https://portal.example.com
-export GATEWAY_SECRET=your-secure-secret-key
-
-caddy run --config Caddyfile
-```
-
 ## Configuration
 
-### Caddyfile
+Env vars only — no Caddyfile directives, no JSON fields:
 
-```caddyfile
-tls {
-    cert_webhook {
-        portal_url https://portal.example.com
-        timeout 30s
-        retry_count 5
-    }
-}
-```
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PORTAL_URL` | Yes | Base URL of the portal service |
+| `GATEWAY_SECRET` | Yes | Shared secret for authentication |
 
-### JSON
+Enable the app in your Caddy JSON config:
 
 ```json
 {
-    "http.handlers": {
-        "cert_webhook": {
-            "portal_url": "https://portal.example.com",
-            "timeout": "30s",
-            "retry_count": 5
-        }
+    "apps": {
+        "cert_webhook": {}
     }
 }
 ```
 
-### Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `PORTAL_URL` | Yes | Base URL of the portal service |
-| `GATEWAY_SECRET` | Yes | Shared secret for authentication |
-
-## Webhook Format
-
-The plugin sends POST requests to `/internal/websites/:domain/ssl-status`:
-
-**Headers:**
-```
-Content-Type: application/json
-X-Gateway-Secret: <configured_secret>
-```
+### Debug Logging
 
-**Body:**
-```json
+```caddyfile
 {
-    "status": "ready",
-    "error": "",
-    "timestamp": "2026-02-26T01:00:00Z"
+    debug
 }
 ```
 
+Enables debug output for event data, webhook delivery, and config resolution.
+
 ## Status Mapping
 
 | Caddy Event | Portal Status |
@@ -112,34 +59,12 @@ X-Gateway-Secret: <configured_secret>
 
 ## Error Handling
 
-- **Transient errors** (5xx, network timeouts): Retried with exponential backoff (5 attempts max)
-- **Permanent errors** (4xx): Logged but not retried
-- Webhook delivery failures do not block certificate operations
+- Webhook delivery failures are logged but do not block certificate operations
 
 ## Development
 
 ```bash
-# Build Caddy with plugin
-xcaddy build --with github.com/LumeWeb/caddy-plugin-cert-webhook
-
-# Run tests
 go test ./...
-
-# Run tests with coverage
-go test -coverprofile=coverage.out ./...
-go tool cover -html=coverage.out -o coverage.html
-
-# Run linters
 go vet ./...
-
-# Format code
 go fmt ./...
-
-# Download dependencies
-go mod download
-go mod tidy
 ```
-
-## License
-
-MIT License - see [LICENSE](LICENSE) for details.

client_test.go

@@ -29,7 +29,7 @@ func TestWebhookDelivery_SuccessfulDelivery(t *testing.T) {
 		},
 	).Return(nil)
 
-	delivery.deliverAsync(context.Background(), "example.com", SSLStatusReady, "", ts)
+	delivery.deliverAsync("example.com", SSLStatusReady, "", ts)
 	delivery.Wait()
 }
 
@@ -51,7 +51,7 @@ func TestWebhookDelivery_ErrorStatus(t *testing.T) {
 		},
 	).Return(nil)
 
-	delivery.deliverAsync(context.Background(), "example.com", SSLStatusFailed, errorMsg, ts)
+	delivery.deliverAsync("example.com", SSLStatusFailed, errorMsg, ts)
 	delivery.Wait()
 }
 
@@ -71,7 +71,7 @@ func TestWebhookDelivery_FailedDelivery(t *testing.T) {
 		},
 	).Return(fmt.Errorf("internal server error"))
 
-	delivery.deliverAsync(context.Background(), "example.com", SSLStatusReady, "", ts)
+	delivery.deliverAsync("example.com", SSLStatusReady, "", ts)
 	delivery.Wait()
 
 	failureLogs := 0
@@ -101,7 +101,7 @@ func TestWebhookDelivery_MultipleConcurrentDeliveries(t *testing.T) {
 				Timestamp: &ts,
 			},
 		).Return(nil)
-		delivery.deliverAsync(context.Background(), domain, SSLStatusReady, "", ts)
+		delivery.deliverAsync(domain, SSLStatusReady, "", ts)
 	}
 
 	delivery.Wait()

config.go

@@ -12,8 +12,8 @@ const (
 )
 
 type Config struct {
-	PortalURL     string `json:"portal_url,omitempty"`
-	GatewaySecret string `json:"-"`
+	PortalURL     string
+	GatewaySecret string
 }
 
 func (c *Config) Provision() {

delivery.go

@@ -28,13 +28,16 @@ const (
 	LogMsgWebhookDeliveryFailed    = "webhook delivery failed"
 )
 
-func (d *WebhookDelivery) deliverAsync(ctx context.Context, domain string, status SSLStatus, errorMsg, timestamp string) {
-	d.wg.Add(1)
-	go func() {
-		defer d.wg.Done()
+func (d *WebhookDelivery) deliverAsync(domain string, status SSLStatus, errorMsg, timestamp string) {
+	d.wg.Go(func() {
 		d.sem <- struct{}{}
 		defer func() { <-d.sem }()
 
+		d.logger.Debug("delivering webhook",
+			zap.String("domain", domain),
+			zap.String("status", string(status)),
+			zap.String("timestamp", timestamp))
+
 		bgCtx := context.Background()
 
 		req := ipfs.SSLStatusUpdateRequest{
@@ -58,7 +61,7 @@ func (d *WebhookDelivery) deliverAsync(ctx context.Context, domain string, statu
 				zap.String("status", string(status)),
 				zap.String("timestamp", timestamp))
 		}
-	}()
+	})
 }
 
 func (d *WebhookDelivery) Wait() {

events.go

@@ -48,7 +48,7 @@ type EventData struct {
 	Error string `json:"error,omitempty"`
 
 	// Raw is the raw event data for debugging
-	Raw map[string]interface{} `json:"-"`
+	Raw map[string]any `json:"-"`
 
 	// EventType is the type of event (cert_obtained, cert_renewed, cert_expired)
 	EventType string `json:"event_type"`
@@ -57,7 +57,7 @@ type EventData struct {
 // Event handlers for certificate lifecycle events
 
 // subscribeToEvents registers handlers for certificate events
-func (h *WebhookHandler) subscribeToEvents(ctx caddy.Context) error {
+func (h *CertWebhookApp) subscribeToEvents(ctx caddy.Context) error {
 	// Get the events app from context
 	eventsAppIface, err := ctx.App("events")
 	if err != nil {
@@ -80,13 +80,11 @@ func (h *WebhookHandler) subscribeToEvents(ctx caddy.Context) error {
 	}
 	h.logger.Info(LogMsgSubscribedToCertObtained)
 
-	// Subscribe to cert_renewed event
 	if err := eventsApp.On(EventCertRenewed, h); err != nil {
 		return fmt.Errorf("failed to subscribe to cert_renewed event: %w", err)
 	}
 	h.logger.Info(LogMsgSubscribedToCertRenewed)
 
-	// Subscribe to cert_expired event
 	if err := eventsApp.On(EventCertExpired, h); err != nil {
 		return fmt.Errorf("failed to subscribe to cert_expired event: %w", err)
 	}
@@ -96,20 +94,22 @@ func (h *WebhookHandler) subscribeToEvents(ctx caddy.Context) error {
 }
 
 // Handle implements caddyevents.Handler interface to process certificate events
-func (h *WebhookHandler) Handle(ctx context.Context, data caddy.Event) error {
+func (h *CertWebhookApp) Handle(ctx context.Context, data caddy.Event) error {
 	eventName := data.Name()
 
 	switch eventName {
 	case EventCertObtained, EventCertRenewed, EventCertExpired:
-		return h.handleCertEvent(ctx, eventName, data)
+		return h.handleCertEvent(eventName, data)
 	default:
 		h.logger.Warn(LogMsgUnknownEventType, zap.String("event", eventName))
 		return nil
 	}
 }
 
 // handleCertEvent processes certificate lifecycle events (obtained, renewed, expired)
-func (h *WebhookHandler) handleCertEvent(ctx context.Context, eventType string, data caddy.Event) error {
+func (h *CertWebhookApp) handleCertEvent(eventType string, data caddy.Event) error {
+	h.logger.Debug("handling cert event", zap.String("event_type", eventType))
+
 	eventData, err := h.extractEventData(eventType, data)
 	if err != nil {
 		h.logger.Error(LogMsgFailedToExtractEventData,
@@ -132,14 +132,14 @@ func (h *WebhookHandler) handleCertEvent(ctx context.Context, eventType string,
 		zap.String("status", string(status)),
 		zap.String("timestamp", eventData.Timestamp))
 
-	return h.sendWebhook(ctx, eventData.Domain, status, eventData.Error, eventData.Timestamp)
+	return h.sendWebhook(eventData.Domain, status, eventData.Error, eventData.Timestamp)
 }
 
 // extractEventData extracts domain, timestamp, and error information from Caddy event data
-func (h *WebhookHandler) extractEventData(eventType string, event caddy.Event) (*EventData, error) {
+func (h *CertWebhookApp) extractEventData(eventType string, event caddy.Event) (*EventData, error) {
 	data := &EventData{
 		EventType: eventType,
-		Raw:       make(map[string]interface{}),
+		Raw:       make(map[string]any),
 	}
 
 	if len(event.Data) == 0 {
@@ -150,7 +150,8 @@ func (h *WebhookHandler) extractEventData(eventType string, event caddy.Event) (
 		return nil, fmt.Errorf("failed to unmarshal event data: %w", err)
 	}
 
-	// Extract timestamp from event data, default to current time
+	h.logger.Debug("raw event data decoded", zap.Any("data", data.Raw))
+
 	if ts, ok := data.Raw["ts"].(float64); ok {
 		sec := int64(ts)
 		nsec := int64((ts - float64(sec)) * 1e9)
@@ -161,13 +162,14 @@ func (h *WebhookHandler) extractEventData(eventType string, event caddy.Event) (
 
 	if domain, ok := data.Raw["domain"].(string); ok {
 		data.Domain = domain
-	} else if san, ok := data.Raw["sans"].([]interface{}); ok && len(san) > 0 {
+	} else if san, ok := data.Raw["sans"].([]any); ok && len(san) > 0 {
 		if d, ok := san[0].(string); ok {
 			data.Domain = d
 		}
 	}
 
 	if data.Domain == "" {
+		h.logger.Debug("no domain found in event data")
 		return nil, fmt.Errorf("no domain found in event data")
 	}
 
@@ -179,7 +181,7 @@ func (h *WebhookHandler) extractEventData(eventType string, event caddy.Event) (
 }
 
 // decodeJSON decodes JSON data from map[string]any to target
-func decodeJSON(data map[string]any, target interface{}) error {
+func decodeJSON(data map[string]any, target any) error {
 	jsonBytes, err := json.Marshal(data)
 	if err != nil {
 		return err