chore(init): review cleanups — reporting hardening and fork-change documentation

- REPORT line: pass the pre-formatted Init Duration/Status fragments as %s
  arguments instead of concatenating them into the Fprintf format string,
  where a runtime-supplied error type containing a formatting verb would
  corrupt the line (the fatal-error scrub regex is unanchored).
- SendInitErrorResponse returns the delegate's error again (pre-branch
  behavior): the /runtime/init/error handler renders an interop error to
  the runtime based on it (e.g. ErrResponseSent during a suppressed init).
- LocalStack adapter POSTs now fail on non-2xx responses (e.g. LocalStack
  rejects a duplicate /status/error with 400, previously treated as
  success) and share one post() helper.
- LOCALSTACK_INIT_PHASE_TIMEOUT is validated (> 0; a 0 previously forced
  every init down the timeout path) and parsed once instead of
  double-defaulting.
- SendInitError fault messages use a blank requestId, matching the
  /init/error path which forwards AWS's blank init-phase requestId; the
  unused uuid dependency is dropped and lsapi.ErrorResponse.RequestId
  reverts to a plain string (never set anywhere), restoring
  internal/lsapi/types.go to its pre-branch state.
- Dedupe the INIT_REPORT line format and the ns->ms conversion.
- Document fork changes per README-LOCALSTACK.md convention: LOCALSTACK
  CHANGES prefix in server_localstack.go and new entries for it and
  internal/lsapi in the custom-changes list.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: joe4dev

README-LOCALSTACK.md

@@ -45,4 +45,6 @@ Document all custom changes with the following comment prefix `# LOCALSTACK CHAN
 
 * Everything in `cmd/localstack`, `cmd/ls-mock`, and `.github`
 * `Makefile` for debugging and building with Docker
+* `internal/lsapi` LocalStack-only package with the request/response types of the LocalStack <-> RIE HTTP API
 * 2023-10-17: `lambda/rapidcore/server.go` pass request metadata into .Reserve(invoke.ID, invoke.TraceID, invoke.LambdaSegmentID)
+* 2026-06-11: `lambda/rapidcore/server_localstack.go` new LocalStack-only file with additions to the rapidcore Server (timeout-aware init await, init-failure drain, structured init-failure interpretation)

cmd/localstack/awsutil.go

@@ -100,15 +100,17 @@ func PrintEndReports(invokeId string, initDuration string, status string, memory
 	_, _ = fmt.Fprintln(w, "END RequestId: "+invokeId)
 	// We set the Max Memory Used and Memory Size to be the same (whatever it is set to) since there is
 	// not a clean way to get this information from rapidcore
+	// initDuration and status are pre-formatted fragments: pass them as %s arguments, not as
+	// part of the format string — status may embed a runtime-supplied error type, and a stray
+	// formatting verb in it would corrupt the REPORT line.
 	_, _ = fmt.Fprintf(w,
 		"REPORT RequestId: %s\t"+
 			"Duration: %.2f ms\t"+
 			"Billed Duration: %.f ms\t"+
 			"Memory Size: %s MB\t"+
 			"Max Memory Used: %s MB\t"+
-			initDuration+
-			status+"\n",
-		invokeId, invokeDuration, math.Ceil(invokeDuration), memorySize, memorySize)
+			"%s%s\n",
+		invokeId, invokeDuration, math.Ceil(invokeDuration), memorySize, memorySize, initDuration, status)
 }
 
 type Sandbox interface {

cmd/localstack/custom_interop.go

@@ -22,7 +22,6 @@ import (
 	"github.com/aws/aws-lambda-runtime-interface-emulator/internal/lambda/rapidcore/standalone"
 	"github.com/aws/aws-lambda-runtime-interface-emulator/internal/lsapi"
 	"github.com/go-chi/chi/v5"
-	"github.com/google/uuid"
 	log "github.com/sirupsen/logrus"
 )
 
@@ -49,7 +48,8 @@ type CustomInteropServer struct {
 	initTimedOut atomic.Bool
 	// initErrorForwarded is set once the runtime's own /init/error has been forwarded to
 	// LocalStack via SendInitErrorResponse, so the crash-path fallback (SendInitError) does
-	// not send a duplicate error status for the same failed initialization.
+	// not send a duplicate error status for the same failed initialization. Unlike
+	// initErrorType below it is never cleared: it only guards the one-shot init-phase report.
 	initErrorForwarded atomic.Bool
 	// initErrorType holds rapidcore's scrubbed fatal error type (e.g. Runtime.Unknown) when init
 	// failed, used to render the INIT_REPORT(phase=invoke) and REPORT Status/Error Type lines for
@@ -83,28 +83,31 @@ const (
 	Error LocalStackStatus = "error"
 )
 
-func (l *LocalStackAdapter) SendStatus(status LocalStackStatus, payload []byte) error {
-	statusUrl := fmt.Sprintf("%s/status/%s/%s", l.UpstreamEndpoint, l.RuntimeId, status)
-	resp, err := http.Post(statusUrl, "application/json", bytes.NewReader(payload))
+// post sends a JSON payload to the given LocalStack endpoint path and fails on non-2xx
+// responses (e.g. LocalStack rejects a duplicate /status/error with 400).
+func (l *LocalStackAdapter) post(path string, payload []byte) error {
+	resp, err := http.Post(l.UpstreamEndpoint+path, "application/json", bytes.NewReader(payload))
 	if err != nil {
 		return err
 	}
 	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("POST %s returned status %d", path, resp.StatusCode)
+	}
 	return nil
 }
 
+func (l *LocalStackAdapter) SendStatus(status LocalStackStatus, payload []byte) error {
+	return l.post(fmt.Sprintf("/status/%s/%s", l.RuntimeId, status), payload)
+}
+
 // SendLogs posts the captured invocation logs to LocalStack.
 func (l *LocalStackAdapter) SendLogs(invokeId string, logs lsapi.LogResponse) error {
 	serialized, err := json.Marshal(logs)
 	if err != nil {
 		return err
 	}
-	resp, err := http.Post(l.UpstreamEndpoint+"/invocations/"+invokeId+"/logs", "application/json", bytes.NewReader(serialized))
-	if err != nil {
-		return err
-	}
-	defer resp.Body.Close()
-	return nil
+	return l.post("/invocations/"+invokeId+"/logs", serialized)
 }
 
 // SendResult posts the invocation result body to LocalStack.
@@ -124,12 +127,7 @@ func (l *LocalStackAdapter) SendResult(invokeId string, body []byte, isError boo
 	} else {
 		log.Infoln("Sending to /response")
 	}
-	resp, err := http.Post(l.UpstreamEndpoint+endpoint, "application/json", bytes.NewReader(body))
-	if err != nil {
-		return err
-	}
-	defer resp.Body.Close()
-	return nil
+	return l.post(endpoint, body)
 }
 
 func NewCustomInteropServer(lsOpts *LsOpts, adapter *LocalStackAdapter, delegate interop.Server, logCollector *LogCollector, eventsAPI *LocalStackEventsAPI) (server *CustomInteropServer) {
@@ -184,11 +182,9 @@ func NewCustomInteropServer(lsOpts *LsOpts, adapter *LocalStackAdapter, delegate
 				if initErrType != "" {
 					initTimeMS, ok := server.eventsAPI.InitDurationMS()
 					if !ok {
-						initTimeMS = float64(time.Since(server.initStart).Nanoseconds()) / float64(time.Millisecond)
+						initTimeMS = millisSince(server.initStart)
 					}
-					_, _ = fmt.Fprintf(logCollector,
-						"INIT_REPORT Init Duration: %.2f ms\tPhase: invoke\tStatus: error\tError Type: %s\n",
-						initTimeMS, initErrType)
+					fprintInitReport(logCollector, initTimeMS, "invoke", "error", initErrType)
 				}
 
 				invokeStart := time.Now()
@@ -302,7 +298,7 @@ func (c *CustomInteropServer) SendErrorResponse(invokeID string, resp *interop.E
 // LocalStack and then propagates it to the delegate. It marks initErrorForwarded so the
 // crash-path fallback in main.go (SendInitError) does not send a duplicate error status for
 // the same failed initialization.
-func (c *CustomInteropServer) SendInitErrorResponse(resp *interop.ErrorInvokeResponse) error {
+func (c *CustomInteropServer) SendInitErrorResponse(resp *interop.ErrorInvokeResponse) (err error) {
 	log.Traceln("SendInitErrorResponse called")
 	// Mark synchronously, before sending: this runs in the init flow before
 	// AwaitInitializedWithDetails unblocks in main.go, so the fallback observes the flag.
@@ -311,8 +307,10 @@ func (c *CustomInteropServer) SendInitErrorResponse(resp *interop.ErrorInvokeRes
 	// INIT_REPORT(phase=invoke) and REPORT Status/Error Type lines (on-demand).
 	c.initErrorType.Store(string(resp.FunctionError.Type))
 
-	// Always cache the structured error in the delegate so the first invoke can surface it.
-	defer c.delegate.SendInitErrorResponse(resp)
+	// Always cache the structured error in the delegate so the first invoke can surface it, and
+	// return its error: the /runtime/init/error handler renders an interop error to the runtime
+	// based on it (e.g. ErrResponseSent during a suppressed init).
+	defer func() { err = c.delegate.SendInitErrorResponse(resp) }()
 
 	// On-demand folds the failed init into the first invocation, which carries the error and
 	// logs; reporting it here via /status/error too would race the invoke and fail the env
@@ -374,15 +372,11 @@ func (c *CustomInteropServer) SendInitError(errType fatalerror.ErrorType, errMsg
 
 	// Match AWS's fault message format "RequestId: <id> Error: <msg>". No invocation is active
 	// during the init phase (LocalStack only dispatches an invoke after the runtime reports
-	// ready), so synthesize a request ID, preferring the current invoke ID if one exists.
-	requestID := c.delegate.GetCurrentInvokeID()
-	if requestID == "" {
-		requestID = uuid.NewString()
-	}
-
+	// ready), so the request id is blank — matching the /init/error path, which forwards AWS's
+	// blank init-phase requestId (see SendInitErrorResponse).
 	payload, err := json.Marshal(lsapi.ErrorResponse{
 		ErrorType:    string(errType),
-		ErrorMessage: fmt.Sprintf("RequestId: %s Error: %s", requestID, message),
+		ErrorMessage: fmt.Sprintf("RequestId: %s Error: %s", c.delegate.GetCurrentInvokeID(), message),
 	})
 	if err != nil {
 		log.WithError(err).Error("Failed to marshal init error response")
@@ -431,9 +425,23 @@ func (c *CustomInteropServer) Init(i *interop.Init, invokeTimeoutMs int64) error
 // invocation (under the function timeout), and that invocation's REPORT omits Init Duration.
 func (c *CustomInteropServer) ReportInitTimeout() {
 	c.initTimedOut.Store(true)
-	initTimeMS := float64(time.Since(c.initStart).Nanoseconds()) / float64(time.Millisecond)
-	_, _ = fmt.Fprintf(c.logCollector,
-		"INIT_REPORT Init Duration: %.2f ms\tPhase: init\tStatus: timeout\n", initTimeMS)
+	fprintInitReport(c.logCollector, millisSince(c.initStart), "init", "timeout", "")
+}
+
+// millisSince returns the wall-clock milliseconds elapsed since start.
+func millisSince(start time.Time) float64 {
+	return float64(time.Since(start).Nanoseconds()) / float64(time.Millisecond)
+}
+
+// fprintInitReport emits an AWS-style INIT_REPORT log line, e.g.
+// "INIT_REPORT Init Duration: 9999.27 ms\tPhase: init\tStatus: timeout" or
+// "INIT_REPORT Init Duration: 0.91 ms\tPhase: invoke\tStatus: error\tError Type: Runtime.ExitError".
+func fprintInitReport(w io.Writer, durationMS float64, phase string, status string, errorType string) {
+	_, _ = fmt.Fprintf(w, "INIT_REPORT Init Duration: %.2f ms\tPhase: %s\tStatus: %s", durationMS, phase, status)
+	if errorType != "" {
+		_, _ = fmt.Fprintf(w, "\tError Type: %s", errorType)
+	}
+	_, _ = fmt.Fprintln(w)
 }
 
 func (c *CustomInteropServer) Invoke(responseWriter http.ResponseWriter, invoke *interop.Invoke) error {

cmd/localstack/main.go

@@ -63,14 +63,14 @@ func InitLsOpts() *LsOpts {
 		RuntimeId:       GetEnvOrDie("LOCALSTACK_RUNTIME_ID"),
 		AccountId:       GetenvWithDefault("LOCALSTACK_FUNCTION_ACCOUNT_ID", "000000000000"),
 		// optional with default
-		InteropPort:      GetenvWithDefault("LOCALSTACK_INTEROP_PORT", "9563"),
-		InitTracingPort:  GetenvWithDefault("LOCALSTACK_RUNTIME_TRACING_PORT", "9564"),
-		User:             GetenvWithDefault("LOCALSTACK_USER", "sbx_user1051"),
-		InitLogLevel:     GetenvWithDefault("LOCALSTACK_INIT_LOG_LEVEL", "warn"),
-		EdgePort:         GetenvWithDefault("EDGE_PORT", "4566"),
-		MaxPayloadSize:   GetenvWithDefault("LOCALSTACK_MAX_PAYLOAD_SIZE", "6291556"),
-		InitPhaseTimeout: GetenvWithDefault("LOCALSTACK_INIT_PHASE_TIMEOUT", strconv.Itoa(defaultInitPhaseTimeoutSeconds)),
+		InteropPort:     GetenvWithDefault("LOCALSTACK_INTEROP_PORT", "9563"),
+		InitTracingPort: GetenvWithDefault("LOCALSTACK_RUNTIME_TRACING_PORT", "9564"),
+		User:            GetenvWithDefault("LOCALSTACK_USER", "sbx_user1051"),
+		InitLogLevel:    GetenvWithDefault("LOCALSTACK_INIT_LOG_LEVEL", "warn"),
+		EdgePort:        GetenvWithDefault("EDGE_PORT", "4566"),
+		MaxPayloadSize:  GetenvWithDefault("LOCALSTACK_MAX_PAYLOAD_SIZE", "6291556"),
 		// optional or empty
+		InitPhaseTimeout:    os.Getenv("LOCALSTACK_INIT_PHASE_TIMEOUT"),
 		CodeArchives:        os.Getenv("LOCALSTACK_CODE_ARCHIVES"),
 		HotReloadingPaths:   strings.Split(GetenvWithDefault("LOCALSTACK_HOT_RELOADING_PATHS", ""), ","),
 		FileWatcherStrategy: os.Getenv("LOCALSTACK_FILE_WATCHER_STRATEGY"),
@@ -276,10 +276,13 @@ func main() {
 	InitHandler(sandbox.LambdaInvokeAPI(), GetEnvOrDie("AWS_LAMBDA_FUNCTION_VERSION"), int64(invokeTimeoutSeconds), bootstrap, lsOpts.AccountId) // TODO: replace this with a custom init
 
 	initPhaseTimeoutSeconds := defaultInitPhaseTimeoutSeconds
-	if parsed, perr := strconv.Atoi(lsOpts.InitPhaseTimeout); perr == nil {
-		initPhaseTimeoutSeconds = parsed
-	} else {
-		log.Warnln("Invalid LOCALSTACK_INIT_PHASE_TIMEOUT, using default:", perr)
+	if lsOpts.InitPhaseTimeout != "" {
+		if parsed, perr := strconv.Atoi(lsOpts.InitPhaseTimeout); perr == nil && parsed > 0 {
+			initPhaseTimeoutSeconds = parsed
+		} else {
+			log.Warnf("Invalid LOCALSTACK_INIT_PHASE_TIMEOUT %q (must be a positive integer); using default %ds",
+				lsOpts.InitPhaseTimeout, defaultInitPhaseTimeoutSeconds)
+		}
 	}
 
 	log.Debugln("Awaiting initialization of runtime init.")

internal/lambda/rapidcore/server_localstack.go

@@ -1,5 +1,8 @@
 package rapidcore
 
+// LOCALSTACK CHANGES 2026-06-11: new LocalStack-only file with additions to the rapidcore
+// Server (timeout-aware init await, init-failure drain, structured init-failure interpretation)
+
 // This file contains LocalStack-specific additions to the rapidcore Server. It is kept
 // separate from server.go (which is vendored upstream from
 // aws-lambda-runtime-interface-emulator) so that upstream stays byte-identical and rebases

internal/lsapi/types.go

@@ -15,10 +15,8 @@ type LogResponse struct {
 
 // ErrorResponse is sent to LocalStack when encountering an error.
 type ErrorResponse struct {
-	ErrorMessage string `json:"errorMessage"`
-	ErrorType    string `json:"errorType,omitempty"`
-	// RequestId uses *string so that an empty string "" is serialized (not omitted),
-	// while nil is omitted — init errors always set this field, fault events leave it nil.
-	RequestId  *string  `json:"requestId,omitempty"`
-	StackTrace []string `json:"stackTrace,omitempty"`
+	ErrorMessage string   `json:"errorMessage"`
+	ErrorType    string   `json:"errorType,omitempty"`
+	RequestId    string   `json:"requestId,omitempty"`
+	StackTrace   []string `json:"stackTrace,omitempty"`
 }