return exit code for synchronous call

.gitignore

@@ -35,3 +35,7 @@ webcmd
 
 key.pem
 cert.pem
+
+*notes*.txt
+*notes*.md
+

README.md

@@ -228,6 +228,35 @@ The `commandTemplate` uses Go's `text/template` syntax to inject data from the H
   Header names are normalized by replacing hyphens (`-`) with underscores (`_`).
   Example: `{{.headers.X_Api_Key}}` or `{{.headers.User_Agent}}` .
 
+## HTTP Response and Error Handling
+
+The server returns different HTTP status codes depending on the outcome of the request and the command execution:
+
+- **200 OK**
+  Returned when the command starts successfully, regardless of whether the command later exits with code 0 or non-zero, or fails while executing.
+  In this case, the handler sets the following response headers:
+  - `X-Success`: `"true"` if the process exit code is 0, otherwise `"false"`.
+  - `X-Exit-Code`: The process exit code (if available).
+  - `X-Error-Message`: Empty on success, or contains the execution error message if the command fails (only if `server.withErrorHeader` is enabled in the configuration).
+
+- **429 Too Many Requests**
+  Returned when command execution cannot start because the call gate rejects the request as busy (e.g., when `mode: single` is used).
+
+- **404 Not Found**
+  Returned when the URL command is missing or the endpoint is not configured.
+
+- **400 Bad Request**
+  Returned when `bodyAsJson` is enabled but the request body is not a valid JSON object.
+
+- **500 Internal Server Error**
+  Returned when the command cannot be prepared or started at all, for example:
+  - Streaming was requested but the `ResponseWriter` does not support flushing.
+  - Command template rendering/building failed.
+  - Gate or pre-action setup failed before the process was started.
+  - Handler configuration is invalid.
+
+**Important distinction:** A command that starts successfully but later fails (e.g., returns a non-zero exit code) is still treated as an HTTP-level success and returns **200 OK**. Detailed information about the process outcome is available in the `X-Success` and `X-Exit-Code` headers. The `X-Error-Message` header is also provided if `server.withErrorHeader` is set to `true` in the configuration.
+
 ## Configuration (`config.yaml`)
 
 ### `server`
@@ -240,6 +269,8 @@ The `commandTemplate` uses Go's `text/template` syntax to inject data from the H
 
 * `shutdownGracePeriod` *(optional)* - the time to wait for active requests to finish before the server shuts down (e.g., `5s`, `30s`). Format: [Go Duration](https://pkg.go.dev/time#ParseDuration). Default: `5s`.
 
+* `withErrorHeader` *(optional)* - if set to `true`, the `X-Error-Message` header will be included in the HTTP response when a command execution fails. Default: `false`.
+
 * `https` *(optional)* - HTTPS configuration:
     * `enabled` - enable or disable HTTPS. Default: `false`.
     * `certFile` - path to the SSL certificate file.

config.sample-ssl.yaml

@@ -1,5 +1,6 @@
 server:
 #  address: "127.0.0.1:8443"
+  withErrorHeader: true
   shutdownGracePeriod: 5s
   https:
     enabled: true

config.sample.yaml

@@ -1,5 +1,6 @@
 server:
   # address: "127.0.0.1:8080"
+  withErrorHeader: true
   shutdownGracePeriod: 5s
 authorization:
   - name: auth-name1

pkg/callgate/callgate_queue.go

@@ -7,32 +7,61 @@ import (
 )
 
 type Sequence struct {
-	token chan struct{}
+	mu    sync.Mutex
+	busy  bool
+	queue []chan struct{} // FIFO of waiters
 }
 
 func NewSequence() *Sequence {
-	l := &Sequence{
-		token: make(chan struct{}, 1),
-	}
-	l.token <- struct{}{}
-
-	return l
+	return &Sequence{} //nolint:exhaustruct
 }
 
 // Acquire blocks until the execution slot is available.
 //
-// This gate allows only one execution at a time. Calls are processed in sequence:
-// if one is running, the next call waits until it completes.
+// This gate allows only one execution at a time.
+// Waiters are served in strict FIFO order.
 //
-// When the slot is acquired, Acquire returns a release function. The caller must
-// call release() when the work is done.
+// When the slot is acquired, Acquire returns a release function.
+// The caller must call release() when the work is done.
 //
 // If the context is canceled before acquiring the slot, Acquire returns ctx.Err().
 func (cg *Sequence) Acquire(ctx context.Context) (func(), error) {
+	// Fast path: not busy and no queue => acquire immediately.
+	cg.mu.Lock()
+	if !cg.busy && len(cg.queue) == 0 {
+		cg.busy = true
+
+		cg.mu.Unlock()
+
+		return cg.releaseFunc(), nil
+	}
+
+	// Otherwise, enqueue and wait for our turn.
+	waiter := make(chan struct{})
+
+	cg.queue = append(cg.queue, waiter)
+	cg.mu.Unlock()
+
 	select {
 	case <-ctx.Done():
-		return nil, fmt.Errorf("acquire sequence: %w", ctx.Err())
-	case <-cg.token:
+		// Remove ourselves from the queue if we haven't been granted the slot yet.
+		cg.mu.Lock()
+		removed := cg.removeWaiterLocked(waiter)
+		cg.mu.Unlock()
+
+		// If we were NOT removed, it means we were already granted (channel closed)
+		// roughly concurrently. In that case, we must return success, not ctx.Err().
+		// We detect "granted" by checking removed==false; but there is a race:
+		// - if channel closed just before we locked, removeWaiterLocked won't find it.
+		// In that case, proceed as acquired.
+		if removed {
+			return nil, fmt.Errorf("acquire sequence: %w", ctx.Err())
+		}
+
+		return cg.releaseFunc(), nil
+
+	case <-waiter:
+		// Granted in FIFO order.
 		return cg.releaseFunc(), nil
 	}
 }
@@ -42,7 +71,37 @@ func (cg *Sequence) releaseFunc() func() {
 
 	return func() {
 		once.Do(func() {
-			cg.token <- struct{}{}
+			cg.mu.Lock()
+			defer cg.mu.Unlock()
+
+			// If someone is waiting, grant the next one in FIFO order.
+			if len(cg.queue) > 0 {
+				next := cg.queue[0]
+				// pop front
+				copy(cg.queue[0:], cg.queue[1:])
+				cg.queue = cg.queue[:len(cg.queue)-1]
+
+				// Keep busy=true, transfer ownership to the next waiter.
+				close(next)
+
+				return
+			}
+
+			// No waiters => free the slot.
+			cg.busy = false
 		})
 	}
 }
+
+func (cg *Sequence) removeWaiterLocked(waiter chan struct{}) bool {
+	for i := range cg.queue {
+		if cg.queue[i] == waiter {
+			copy(cg.queue[i:], cg.queue[i+1:])
+			cg.queue = cg.queue[:len(cg.queue)-1]
+
+			return true
+		}
+	}
+
+	return false
+}