3 Commits

8 changed files with 276 additions and 4 deletions

View File

@@ -45,6 +45,9 @@ boundary and constraints that framework work must preserve.
## Release Guidance ## Release Guidance
The [v0.23.3 release notes](docs/releases/v0.23.3.md) cover HTTP operation-timeout
attribution, custom caller cancellation causes, and response-read error identity.
The [v0.23.2 release notes](docs/releases/v0.23.2.md) cover configuration, The [v0.23.2 release notes](docs/releases/v0.23.2.md) cover configuration,
validation, and release-tool dependency updates without an API migration or validation, and release-tool dependency updates without an API migration or
Go minimum increase. Go minimum increase.

View File

@@ -0,0 +1,97 @@
package promptkit_test
import (
"context"
"errors"
"net/http"
"net/url"
"strings"
"testing"
"testing/synctest"
"time"
"go.maximumdirect.net/promptkit"
)
type contextIdentityResponseBody struct {
ctx context.Context
cause error
}
func (b contextIdentityResponseBody) Read([]byte) (int, error) { <-b.ctx.Done(); return 0, b.cause }
func (contextIdentityResponseBody) Close() error { return nil }
func TestExecutionContextAndOriginalCauseIdentities(t *testing.T) {
for _, split := range []bool{false, true} {
for _, kind := range []string{"caller cancel", "caller deadline", "body operation deadline"} {
t.Run(map[bool]string{false: "run/", true: "prepared/"}[split]+kind, func(t *testing.T) {
synctest.Test(t, func(t *testing.T) {
cause := errors.New("private original cause")
ctx, cancel := context.WithCancelCause(context.Background())
defer cancel(nil)
want := error(context.Canceled)
failure := promptkit.ExecutionFailureCanceled
if kind == "caller deadline" {
var stop context.CancelFunc
ctx, stop = context.WithTimeoutCause(context.Background(), time.Second, cause)
defer stop()
}
if kind != "caller cancel" {
want = context.DeadlineExceeded
failure = promptkit.ExecutionFailureDeadline
}
cfg := simpleConfig("message")
cfg.HTTPClient = &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
if kind == "body operation deadline" {
return &http.Response{StatusCode: http.StatusOK, Body: contextIdentityResponseBody{ctx: r.Context(), cause: cause}}, nil
}
if kind == "caller cancel" {
cancel(cause)
} else {
<-ctx.Done()
}
return nil, context.Cause(ctx)
})}
engine, err := promptkit.NewEngine(cfg)
if err != nil {
t.Fatal(err)
}
var events []promptkit.ExecutionEvent
req := simpleGenerationRequest()
req.OperationTimeout = time.Minute
if kind == "body operation deadline" {
req.OperationTimeout = time.Second
}
req.Observer = func(e promptkit.ExecutionEvent) { events = append(events, e) }
var result *promptkit.RunResult
if split {
handle, prepareErr := engine.PrepareExecution(ctx, req)
if prepareErr != nil {
t.Fatal(prepareErr)
}
result, err = engine.RunPrepared(ctx, handle)
} else {
result, err = engine.Run(ctx, req)
}
for _, identity := range []error{want, cause, promptkit.ErrLLMGenerate, promptkit.ErrTransport} {
if !errors.Is(err, identity) {
t.Errorf("error=%v, want identity %v", err, identity)
}
}
if kind != "body operation deadline" {
var transportErr *url.Error
if !errors.As(err, &transportErr) {
t.Errorf("lost HTTP transport error: %v", err)
}
}
if result != nil || errors.Is(err, promptkit.ErrOperationTimeout) != (kind == "body operation deadline") || strings.Contains(err.Error(), cause.Error()) {
t.Fatalf("incorrect outcome or disclosure: result=%v error=%v", result, err)
}
if len(events) != 3 || events[1].Failure != failure || events[2].Kind != promptkit.ExecutionFinished || events[2].Failure != failure {
t.Fatalf("attempt/terminal classification = %+v", events)
}
})
})
}
}
}

View File

@@ -159,6 +159,13 @@ caller deadlines, generation deadlines, and whole-request client timeouts
retain `context.DeadlineExceeded`. The runner adds its generation category retain `context.DeadlineExceeded`. The runner adds its generation category
without discarding those identities or depending on HTTP status mapping. without discarding those identities or depending on HTTP status mapping.
When a transport failure carries a custom context cancellation cause, the
client also retains the standard context identity. It correlates that cause
with the returned failure rather than labeling unrelated transport errors from
context state alone. Cancellation while reading a successful response body
retains the original read failure alongside the context identity within the
redacting wrapper.
## Test Ownership ## Test Ownership
The The

36
docs/releases/v0.23.3.md Normal file
View File

@@ -0,0 +1,36 @@
# Promptkit v0.23.3
This patch release corrects timeout attribution and preserves error identities
in the built-in OpenAI-compatible HTTP client.
## Fixed
- Operation budgets expiring during an in-flight HTTP generation request now
match both `ErrOperationTimeout` and `context.DeadlineExceeded`. Terminal
observations report a deadline failure instead of a transport failure.
- HTTP failures carrying custom caller cancellation or deadline causes retain
both the custom cause and the standard context identity. Unrelated transport
failures are not relabeled solely because a context has been canceled.
- Cancellation while reading a successful response body preserves the original
reader error alongside the context identity, without exposing its diagnostic
text through the redacted error message.
Regression coverage exercises `Run` and `RunPrepared`, public error identities,
and attempt and terminal classifications. See the [request and timeout
contracts](../../types.go), [public error GoDoc](../../engine.go), and
[error-handling guide](../consumers/pkg-promptkit.md#handle-errors).
## Compatibility And Upgrade
No configuration or request API migration is required from v0.23.2. Consumers
using `errors.Is` for cancellation or deadline handling now receive the
correct identities on the affected paths; applications continue to own their
status mapping and diagnostic presentation.
The Go consumer minimum remains 1.27.0, and dependency versions are unchanged.
```sh
go get go.maximumdirect.net/promptkit@v0.23.3
```
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/oss/attribution.md)

View File

@@ -3,6 +3,9 @@ package promptkit_test
import ( import (
"context" "context"
"errors" "errors"
"net/http"
"net/http/httptest"
"net/url"
"testing" "testing"
"testing/synctest" "testing/synctest"
"time" "time"
@@ -10,6 +13,70 @@ import (
"go.maximumdirect.net/promptkit" "go.maximumdirect.net/promptkit"
) )
func TestBuiltInGenerationOperationTimeout(t *testing.T) {
for _, split := range []bool{false, true} {
t.Run(map[bool]string{false: "run", true: "prepared"}[split], func(t *testing.T) {
started := make(chan struct{}, 1)
release := make(chan struct{})
provider := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
select {
case started <- struct{}{}:
default:
}
<-release
}))
defer provider.Close()
defer close(release)
config := simpleConfig("message")
zero := 0
config.TransientRetries = &zero
config.HTTPClient = provider.Client()
engine, err := promptkit.NewEngine(config)
if err != nil {
t.Fatal(err)
}
var terminal promptkit.ExecutionEvent
req := promptkit.RunRequest{PromptID: "prompt", OperationTimeout: time.Second,
Execution: &promptkit.ExecutionTargetOverride{Endpoint: provider.URL + "/v1", TimeoutSeconds: &zero},
Observer: func(event promptkit.ExecutionEvent) {
if event.Kind == promptkit.ExecutionFinished {
terminal = event
}
},
}
parent := context.Background()
var result *promptkit.RunResult
if split {
handle, prepareErr := engine.PrepareExecution(parent, req)
if prepareErr != nil {
t.Fatal(prepareErr)
}
result, err = engine.RunPrepared(parent, handle)
} else {
result, err = engine.Run(parent, req)
}
select {
case <-started:
default:
t.Fatal("operation expired before provider received the request")
}
for _, target := range []error{promptkit.ErrOperationTimeout, context.DeadlineExceeded, promptkit.ErrLLMGenerate, promptkit.ErrTransport} {
if !errors.Is(err, target) {
t.Errorf("error=%v, want identity %v", err, target)
}
}
var transportErr *url.Error
if !errors.As(err, &transportErr) {
t.Errorf("error=%v, want retained HTTP transport cause", err)
}
if result != nil || parent.Err() != nil || terminal.Failure != promptkit.ExecutionFailureDeadline {
t.Fatalf("result=%v parent=%v terminal=%+v", result, parent.Err(), terminal)
}
})
}
}
func TestRunOperationTimeoutAttribution(t *testing.T) { func TestRunOperationTimeoutAttribution(t *testing.T) {
synctest.Test(t, func(t *testing.T) { synctest.Test(t, func(t *testing.T) {
engine := observationEngine(t, observationClientFunc(func(ctx context.Context, _ promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) { engine := observationEngine(t, observationClientFunc(func(ctx context.Context, _ promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) {

View File

@@ -0,0 +1,50 @@
package llm
import (
"context"
"errors"
"net/http"
"strings"
"testing"
"go.maximumdirect.net/promptkit/internal/domain"
)
func TestTransportDoesNotRelabelIndependentFailureAfterCancellation(t *testing.T) {
ctx, cancel := context.WithCancelCause(context.Background())
defer cancel(nil)
independent := errors.New("independent transport failure")
client := NewOpenAICompatibleClient(OpenAICompatibleConfig{HTTPClient: &http.Client{Transport: roundTripFunc(func(*http.Request) (*http.Response, error) {
cancel(errors.New("unrelated caller cause"))
return nil, independent
})}})
_, err := client.Generate(ctx, contextIdentityRequest())
if !errors.Is(err, independent) || errors.Is(err, context.Canceled) {
t.Fatalf("unrelated failure relabeled: %v", err)
}
}
type contextIdentityBody struct {
cancel context.CancelFunc
cause error
}
func (b contextIdentityBody) Read([]byte) (int, error) { b.cancel(); return 0, b.cause }
func (contextIdentityBody) Close() error { return nil }
func TestResponseReadCancellationRetainsOriginalCause(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
cause := errors.New("private body failure")
client := NewOpenAICompatibleClient(OpenAICompatibleConfig{HTTPClient: &http.Client{Transport: roundTripFunc(func(*http.Request) (*http.Response, error) {
return &http.Response{StatusCode: http.StatusOK, Body: contextIdentityBody{cancel: cancel, cause: cause}}, nil
})}})
_, err := client.Generate(ctx, contextIdentityRequest())
if !errors.Is(err, context.Canceled) || !errors.Is(err, cause) || !errors.Is(err, ErrTransport) || strings.Contains(err.Error(), cause.Error()) {
t.Fatalf("lost body cause or redaction: %v", err)
}
}
func contextIdentityRequest() domain.GenerateRequest {
return domain.GenerateRequest{Target: domain.ExecutionTarget{Endpoint: "http://example.test/v1", Model: "test"}}
}

View File

@@ -220,6 +220,13 @@ func (p *PreparedGeneration) execute(ctx context.Context, captureEvidence bool)
outcome.StatusCode = httpResp.StatusCode outcome.StatusCode = httpResp.StatusCode
} }
if err != nil { if err != nil {
// net/http can return the context's custom cause instead of ctx.Err().
// Add the standard identity only when the transport failure carries that
// cause; an unrelated failure must not acquire a later cancellation.
if contextErr := requestContext.Err(); contextErr != nil &&
!errors.Is(err, contextErr) && errors.Is(err, context.Cause(requestContext)) {
err = errors.Join(contextErr, err)
}
outcome.Err = &requestFailedError{cause: err} outcome.Err = &requestFailedError{cause: err}
return outcome return outcome
} }
@@ -234,7 +241,9 @@ func (p *PreparedGeneration) execute(ctx context.Context, captureEvidence bool)
httpResp.ContentLength, httpResp.ContentLength,
httpResp.Body, httpResp.Body,
) )
if err := observedContextError(requestContext, ctx, outcome.Err); err != nil { // The provider status is already captured separately. Context failure
// supersedes it, rather than nesting a provider-status error as transport.
if err := observedContextError(requestContext, ctx, nil); err != nil {
outcome.Err = err outcome.Err = err
} }
return outcome return outcome
@@ -300,10 +309,10 @@ func (p *PreparedGeneration) execute(ctx context.Context, captureEvidence bool)
func observedContextError(attempt, caller context.Context, cause error) error { func observedContextError(attempt, caller context.Context, cause error) error {
if err := caller.Err(); err != nil { if err := caller.Err(); err != nil {
return &requestFailedError{cause: err} return &requestFailedError{cause: errors.Join(err, cause)}
} }
if err := attempt.Err(); err != nil { if err := attempt.Err(); err != nil {
return &requestFailedError{cause: err} return &requestFailedError{cause: errors.Join(err, cause)}
} }
if errors.Is(cause, context.Canceled) || errors.Is(cause, context.DeadlineExceeded) { if errors.Is(cause, context.Canceled) || errors.Is(cause, context.DeadlineExceeded) {
return &requestFailedError{cause: cause} return &requestFailedError{cause: cause}

View File

@@ -3,6 +3,7 @@ package usecase
import ( import (
"context" "context"
"errors" "errors"
"fmt"
"time" "time"
) )
@@ -17,7 +18,9 @@ type OperationScope struct {
func NewOperationScope(parent context.Context, duration time.Duration) *OperationScope { func NewOperationScope(parent context.Context, duration time.Duration) *OperationScope {
scope := &OperationScope{Context: parent, cancel: func() {}} scope := &OperationScope{Context: parent, cancel: func() {}}
if duration > 0 { if duration > 0 {
scope.cause = errors.New("operation deadline") // Transports may return context.Cause rather than ctx.Err(). Retain
// deadline identity while keeping this cause unique to the invocation.
scope.cause = fmt.Errorf("operation deadline: %w", context.DeadlineExceeded)
scope.Context, scope.cancel = context.WithTimeoutCause(parent, duration, scope.cause) scope.Context, scope.cancel = context.WithTimeoutCause(parent, duration, scope.cause)
} }
return scope return scope