Enforce runtime report contracts and recoverable session exports
This commit is contained in:
+171
-60
@@ -4,7 +4,9 @@ import (
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"git.a-wan.net/alan/pipelines/internal/protocol"
|
||||
@@ -15,6 +17,10 @@ import (
|
||||
// never presented as the whole session.
|
||||
const MaxSessionExport = 8 << 20
|
||||
|
||||
var ErrEmptySessionExport = errors.New("session recorded but native export contains no messages")
|
||||
var errTransientExport = errors.New("native session export temporarily unavailable")
|
||||
var errSessionIdentity = errors.New("native export session identity mismatch")
|
||||
|
||||
// nativeExportResult is one bounded `opencode export` readback. envelope is the
|
||||
// stdout prefix the CLI wrote, capped at the caller's limit; truncated is true
|
||||
// when the CLI wrote more than the cap, so the prefix is not valid whole JSON.
|
||||
@@ -45,6 +51,15 @@ func exportNative(ctx context.Context, executable, directory, backend, id string
|
||||
cmd.Stdout = stdout
|
||||
cmd.Stderr = stderr
|
||||
if err := cmd.Run(); err != nil {
|
||||
// Only known temporary transport/store failures are retried. Do not
|
||||
// expose stderr: it may contain session text or credentials.
|
||||
text := strings.ToLower(string(stderr.Bytes()))
|
||||
for _, temporary := range []string{"temporarily unavailable", "connection refused", "database is locked", "server is busy"} {
|
||||
if strings.Contains(text, temporary) {
|
||||
err = errors.Join(errTransientExport, err)
|
||||
break
|
||||
}
|
||||
}
|
||||
return nativeExportResult{envelope: stdout.Bytes(), truncated: stdout.overflow}, err
|
||||
}
|
||||
return nativeExportResult{envelope: stdout.Bytes(), truncated: stdout.overflow}, nil
|
||||
@@ -52,18 +67,47 @@ func exportNative(ctx context.Context, executable, directory, backend, id string
|
||||
|
||||
// validNativeExport is the exact-ID and messages-array validation
|
||||
// Connection.Messages and ExportSession share: the envelope must parse, carry an
|
||||
// info.id equal to wantID and a non-empty JSON messages array.
|
||||
// info.id equal to wantID and a JSON messages array. An empty array is valid
|
||||
// readback syntax, not complete evidence; consumers must label it empty.
|
||||
func validNativeExport(data []byte, wantID string) (json.RawMessage, bool) {
|
||||
var envelope struct {
|
||||
Info struct {
|
||||
ID string `json:"id"`
|
||||
} `json:"info"`
|
||||
Messages json.RawMessage `json:"messages"`
|
||||
Data json.RawMessage `json:"data"`
|
||||
}
|
||||
if json.Unmarshal(data, &envelope) != nil || envelope.Info.ID != wantID || len(envelope.Messages) == 0 || envelope.Messages[0] != '[' {
|
||||
if json.Unmarshal(data, &envelope) != nil {
|
||||
return nil, false
|
||||
}
|
||||
return envelope.Messages, true
|
||||
// The HTTP/CLI readback can wrap a payload in data. Only unwrap an
|
||||
// otherwise absent envelope, never use data to override a mismatched ID.
|
||||
if envelope.Info.ID == "" && len(envelope.Messages) == 0 && len(envelope.Data) > 0 {
|
||||
if json.Unmarshal(envelope.Data, &envelope) != nil {
|
||||
return nil, false
|
||||
}
|
||||
}
|
||||
if envelope.Info.ID != wantID || len(envelope.Messages) == 0 {
|
||||
return nil, false
|
||||
}
|
||||
messages := bytes.TrimSpace(envelope.Messages)
|
||||
if len(messages) > 0 && messages[0] == '{' {
|
||||
var wrapped struct {
|
||||
Data json.RawMessage `json:"data"`
|
||||
}
|
||||
if json.Unmarshal(messages, &wrapped) != nil {
|
||||
return nil, false
|
||||
}
|
||||
messages = bytes.TrimSpace(wrapped.Data)
|
||||
}
|
||||
if len(messages) == 0 || messages[0] != '[' {
|
||||
return nil, false
|
||||
}
|
||||
var records []json.RawMessage
|
||||
if json.Unmarshal(messages, &records) != nil {
|
||||
return nil, false
|
||||
}
|
||||
return messages, true
|
||||
}
|
||||
|
||||
// ExportedPart is one decoded content element of an exported session. Raw keeps
|
||||
@@ -94,6 +138,7 @@ type ExportedMessage struct {
|
||||
// export. Truncated is true when the source exceeded MaxSessionExport; Messages
|
||||
// then covers the complete turns decoded before the cut.
|
||||
type ExportedSession struct {
|
||||
Attempts int
|
||||
ID string
|
||||
Backend string
|
||||
Messages []ExportedMessage
|
||||
@@ -105,68 +150,123 @@ type ExportedSession struct {
|
||||
// decodes the v1/v2 message and part shapes through chatMessageRecords and, when
|
||||
// the source exceeded MaxSessionExport, streams the complete turns decoded from
|
||||
// the bounded prefix and reports Truncated instead of failing. It performs no
|
||||
// writes, no resumption, no idleness wait and no retries.
|
||||
// writes, no resumption and no idleness wait. Empty readbacks and explicitly
|
||||
// temporary failures get at most three attempts within the caller's deadline;
|
||||
// wrong identity and permanent failures never retry.
|
||||
func ExportSession(ctx context.Context, executable, directory, backend, id string) (ExportedSession, error) {
|
||||
if !sessionID.MatchString(id) {
|
||||
return ExportedSession{}, fmt.Errorf("invalid session ID")
|
||||
}
|
||||
exported, err := exportNative(ctx, executable, directory, backend, id, MaxSessionExport)
|
||||
if err != nil {
|
||||
if ctx.Err() != nil {
|
||||
return ExportedSession{}, ctx.Err()
|
||||
}
|
||||
return ExportedSession{}, fmt.Errorf("native session export failed: %w", err)
|
||||
}
|
||||
session := ExportedSession{ID: id, Backend: backend}
|
||||
if !exported.truncated {
|
||||
messages, ok := validNativeExport(exported.envelope, id)
|
||||
if !ok {
|
||||
// The CLI can observe a session whose final write is still landing
|
||||
// (the stage just settled). One short, bounded retry recovers the
|
||||
// session evidence instead of dropping session.html for the stage.
|
||||
timer := time.NewTimer(200 * time.Millisecond)
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
timer.Stop()
|
||||
return ExportedSession{}, ctx.Err()
|
||||
case <-timer.C:
|
||||
}
|
||||
retried, retryErr := exportNative(ctx, executable, directory, backend, id, MaxSessionExport)
|
||||
if retryErr != nil {
|
||||
if ctx.Err() != nil {
|
||||
return ExportedSession{}, ctx.Err()
|
||||
}
|
||||
return ExportedSession{}, fmt.Errorf("native session export failed: %w", retryErr)
|
||||
}
|
||||
exported = retried
|
||||
if !exported.truncated {
|
||||
messages, ok = validNativeExport(exported.envelope, id)
|
||||
if !ok {
|
||||
return ExportedSession{}, fmt.Errorf("native export returned invalid or mismatched session evidence")
|
||||
}
|
||||
}
|
||||
}
|
||||
if !exported.truncated {
|
||||
records, err := chatMessageRecords(messages)
|
||||
if err != nil {
|
||||
return ExportedSession{}, err
|
||||
}
|
||||
session.Messages = exportedMessages(records)
|
||||
for attempt := 0; attempt < 3; attempt++ {
|
||||
session, err := exportSessionOnce(ctx, executable, directory, backend, id)
|
||||
session.Attempts = attempt + 1
|
||||
if err == nil {
|
||||
return session, nil
|
||||
}
|
||||
if ctx.Err() != nil {
|
||||
return session, ctx.Err()
|
||||
}
|
||||
if attempt == 2 || (!errors.Is(err, ErrEmptySessionExport) && !errors.Is(err, errTransientExport)) {
|
||||
return session, err
|
||||
}
|
||||
// Bounded recovery, not a causal claim about why readback was empty.
|
||||
timer := time.NewTimer(time.Duration(attempt+1) * 200 * time.Millisecond)
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
timer.Stop()
|
||||
return session, ctx.Err()
|
||||
case <-timer.C:
|
||||
}
|
||||
}
|
||||
// The source exceeded the cap, so the session is larger than what was read
|
||||
// and must never be presented as whole. The prefix still yields every turn
|
||||
// that decoded before the cut.
|
||||
records, _, err := decodeExportPrefix(exported.envelope, id)
|
||||
panic("unreachable")
|
||||
}
|
||||
|
||||
func exportSessionOnce(ctx context.Context, executable, directory, backend, id string) (ExportedSession, error) {
|
||||
session := ExportedSession{ID: id, Backend: backend}
|
||||
exported, err := exportNative(ctx, executable, directory, backend, id, MaxSessionExport)
|
||||
if err != nil {
|
||||
return ExportedSession{}, err
|
||||
return session, fmt.Errorf("native session export failed: %w", err)
|
||||
}
|
||||
if exported.truncated {
|
||||
records, _, err := decodeExportPrefix(exported.envelope, id)
|
||||
if err != nil {
|
||||
return session, err
|
||||
}
|
||||
session.Messages, session.Truncated = exportedMessages(records), true
|
||||
if len(session.Messages) == 0 {
|
||||
return session, ErrEmptySessionExport
|
||||
}
|
||||
return session, nil
|
||||
}
|
||||
messages, ok := validNativeExport(exported.envelope, id)
|
||||
if !ok {
|
||||
// Incomplete JSON is a possible interrupted read; valid but wrong
|
||||
// identity/schema is permanent and must never be retried as settling.
|
||||
var syntax *json.SyntaxError
|
||||
var envelope struct {
|
||||
Info struct {
|
||||
ID string `json:"id"`
|
||||
} `json:"info"`
|
||||
Data json.RawMessage `json:"data"`
|
||||
}
|
||||
if err := json.Unmarshal(exported.envelope, &envelope); err != nil {
|
||||
identity := exportPrefixIdentity(exported.envelope)
|
||||
if identity != "" && identity != id {
|
||||
return session, errSessionIdentity
|
||||
}
|
||||
if identity == id && errors.As(err, &syntax) && strings.Contains(syntax.Error(), "unexpected end") {
|
||||
return session, errTransientExport
|
||||
}
|
||||
return session, fmt.Errorf("native export returned invalid session evidence")
|
||||
}
|
||||
if envelope.Info.ID == "" && len(envelope.Data) > 0 {
|
||||
_ = json.Unmarshal(envelope.Data, &envelope)
|
||||
}
|
||||
if envelope.Info.ID != "" && envelope.Info.ID != id {
|
||||
return session, errSessionIdentity
|
||||
}
|
||||
return session, fmt.Errorf("native export returned unsupported or missing session evidence")
|
||||
}
|
||||
records, err := chatMessageRecords(messages)
|
||||
if err != nil {
|
||||
return session, err
|
||||
}
|
||||
session.Messages = exportedMessages(records)
|
||||
session.Truncated = true
|
||||
if len(session.Messages) == 0 {
|
||||
return session, ErrEmptySessionExport
|
||||
}
|
||||
return session, nil
|
||||
}
|
||||
|
||||
// exportPrefixIdentity reads only complete metadata preceding an interrupted
|
||||
// messages array. A known wrong session is permanent even when JSON is cut.
|
||||
func exportPrefixIdentity(data []byte) string {
|
||||
decoder := json.NewDecoder(bytes.NewReader(data))
|
||||
if token, err := decoder.Token(); err != nil || token != json.Delim('{') {
|
||||
return ""
|
||||
}
|
||||
for decoder.More() {
|
||||
token, err := decoder.Token()
|
||||
if err != nil {
|
||||
return ""
|
||||
}
|
||||
if token == "info" {
|
||||
var info struct {
|
||||
ID string `json:"id"`
|
||||
}
|
||||
if decoder.Decode(&info) == nil {
|
||||
return info.ID
|
||||
}
|
||||
return ""
|
||||
}
|
||||
var skip json.RawMessage
|
||||
if decoder.Decode(&skip) != nil {
|
||||
return ""
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// exportedMessages maps decoded native turns onto ExportedMessage, preserving
|
||||
// every role and each part's raw JSON for unknown types.
|
||||
func exportedMessages(records []nativeChatMessage) []ExportedMessage {
|
||||
@@ -209,10 +309,17 @@ func decodeExportPrefix(data []byte, wantID string) ([]nativeChatMessage, bool,
|
||||
}
|
||||
var messages []nativeChatMessage
|
||||
sawMessages := false
|
||||
sawIdentity := false
|
||||
partial := func() ([]nativeChatMessage, bool, error) {
|
||||
if !sawIdentity {
|
||||
return nil, false, fmt.Errorf("native export prefix has no verified session identity")
|
||||
}
|
||||
return messages, true, nil
|
||||
}
|
||||
for decoder.More() {
|
||||
keyToken, err := decoder.Token()
|
||||
if err != nil {
|
||||
return messages, true, nil
|
||||
return partial()
|
||||
}
|
||||
key, _ := keyToken.(string)
|
||||
switch key {
|
||||
@@ -221,16 +328,17 @@ func decodeExportPrefix(data []byte, wantID string) ([]nativeChatMessage, bool,
|
||||
ID string `json:"id"`
|
||||
}
|
||||
if err := decoder.Decode(&info); err != nil {
|
||||
return messages, true, nil
|
||||
return partial()
|
||||
}
|
||||
if info.ID != "" && info.ID != wantID {
|
||||
if info.ID != wantID {
|
||||
return nil, false, fmt.Errorf("native export session id mismatch")
|
||||
}
|
||||
sawIdentity = true
|
||||
case "messages":
|
||||
sawMessages = true
|
||||
open, err := decoder.Token()
|
||||
if err != nil {
|
||||
return messages, true, nil
|
||||
return partial()
|
||||
}
|
||||
if delim, ok := open.(json.Delim); !ok || delim != '[' {
|
||||
return nil, false, fmt.Errorf("native export returned invalid session evidence")
|
||||
@@ -238,25 +346,28 @@ func decodeExportPrefix(data []byte, wantID string) ([]nativeChatMessage, bool,
|
||||
for decoder.More() {
|
||||
var message nativeChatMessage
|
||||
if err := decoder.Decode(&message); err != nil {
|
||||
return messages, true, nil
|
||||
return partial()
|
||||
}
|
||||
messages = append(messages, message)
|
||||
}
|
||||
if _, err := decoder.Token(); err != nil {
|
||||
return messages, true, nil
|
||||
return partial()
|
||||
}
|
||||
default:
|
||||
var skip json.RawMessage
|
||||
if err := decoder.Decode(&skip); err != nil {
|
||||
return messages, true, nil
|
||||
return partial()
|
||||
}
|
||||
}
|
||||
}
|
||||
if !sawMessages {
|
||||
return nil, false, fmt.Errorf("native export returned no session messages")
|
||||
}
|
||||
if !sawIdentity {
|
||||
return nil, false, fmt.Errorf("native export prefix has no verified session identity")
|
||||
}
|
||||
if _, err := decoder.Token(); err != nil {
|
||||
return messages, true, nil
|
||||
return partial()
|
||||
}
|
||||
return messages, false, nil
|
||||
}
|
||||
|
||||
@@ -2,6 +2,9 @@ package opencode
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
@@ -73,7 +76,30 @@ func TestExportSessionDecodesRolesPartsAndUnknownTypes(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestExportSessionRetriesOneSettlingReadback(t *testing.T) {
|
||||
func TestNativeExportEnvelopeNormalizationRetainsExactIdentity(t *testing.T) {
|
||||
for _, data := range []string{
|
||||
`{"info":{"id":"ses_ok"},"messages":[]}`,
|
||||
`{"info":{"id":"ses_ok"},"messages":{"data":[]}}`,
|
||||
`{"data":{"info":{"id":"ses_ok"},"messages":[]}}`,
|
||||
} {
|
||||
messages, ok := validNativeExport([]byte(data), "ses_ok")
|
||||
if !ok || string(messages) != "[]" {
|
||||
t.Fatalf("envelope not normalized: %s %s %v", data, messages, ok)
|
||||
}
|
||||
}
|
||||
for _, data := range []string{
|
||||
`{"info":{"id":"ses_other"},"messages":[],"data":{"info":{"id":"ses_ok"},"messages":[]}}`,
|
||||
`{"info":{"id":"ses_ok"},"messages":null}`,
|
||||
`{"info":{"id":"ses_ok"},"messages":{}}`,
|
||||
`{"data":{"info":{"id":"ses_other"},"messages":[]}}`,
|
||||
} {
|
||||
if _, ok := validNativeExport([]byte(data), "ses_ok"); ok {
|
||||
t.Fatalf("invalid identity/envelope accepted: %s", data)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestExportSessionRetriesOneInvalidReadbackWithoutCausalClaim(t *testing.T) {
|
||||
id := "ses_settle"
|
||||
dir := t.TempDir()
|
||||
count := filepath.Join(dir, "count")
|
||||
@@ -83,7 +109,7 @@ func TestExportSessionRetriesOneSettlingReadback(t *testing.T) {
|
||||
"[ \"$1\" = " + id + " ] || exit 9\n" +
|
||||
"if [ ! -f " + count + " ]; then\n" +
|
||||
" echo 1 > " + count + "\n" +
|
||||
" echo '{\"info\":{\"id\":\"wrong\"}}'\n" +
|
||||
" echo '{\"info\":{\"id\":\"ses_settle\"},\"messages\":['\n" +
|
||||
" exit 0\n" +
|
||||
"fi\n" +
|
||||
"cat <<'EOF'\n" + valid + "\nEOF\n"
|
||||
@@ -181,3 +207,42 @@ func TestDecodeExportPrefixRejectsMismatchedID(t *testing.T) {
|
||||
t.Fatal("mismatched prefix session accepted")
|
||||
}
|
||||
}
|
||||
|
||||
func TestExportRecoveryRetriesOnlyTransientOrEmptyReadback(t *testing.T) {
|
||||
for _, tc := range []struct {
|
||||
name, first string
|
||||
wantAttempts int
|
||||
empty bool
|
||||
wantError bool
|
||||
}{
|
||||
{"empty-then-ready", `echo '{"info":{"id":"ses_ok"},"messages":[]}'`, 2, false, false},
|
||||
{"temporary-then-ready", `echo 'database is locked' >&2; exit 1`, 2, false, false},
|
||||
{"wrong-session", `echo '{"info":{"id":"ses_wrong"},"messages":[]}'`, 1, false, true},
|
||||
{"wrong-session-incomplete", `echo '{"info":{"id":"ses_wrong"},"messages":['`, 1, false, true},
|
||||
{"unsupported-schema", `echo '{"info":{"id":"ses_ok"},"messages":{}}'`, 1, false, true},
|
||||
{"permanent-cli-error", `echo 'session not found' >&2; exit 1`, 1, false, true},
|
||||
{"always-empty", `echo '{"info":{"id":"ses_ok"},"messages":[]}'`, 3, true, true},
|
||||
} {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
count := filepath.Join(dir, "calls")
|
||||
script := "#!/bin/sh\nn=0; [ ! -f '" + count + "' ] || n=$(cat '" + count + "'); n=$((n+1)); echo $n > '" + count + "'\n"
|
||||
if tc.empty {
|
||||
script += tc.first + "\n"
|
||||
} else {
|
||||
script += "if [ $n = 1 ]; then " + tc.first + "; else echo '{\"info\":{\"id\":\"ses_ok\"},\"messages\":[{\"info\":{\"role\":\"assistant\"},\"parts\":[{\"type\":\"text\",\"text\":\"ready\"}]}]}'; fi\n"
|
||||
}
|
||||
session, err := ExportSession(context.Background(), writeFixture(t, script), dir, "v2", "ses_ok")
|
||||
if (err != nil) != tc.wantError {
|
||||
t.Fatalf("unexpected result %+v %v", session, err)
|
||||
}
|
||||
calls, _ := os.ReadFile(count)
|
||||
if strings.TrimSpace(string(calls)) != fmt.Sprint(tc.wantAttempts) || session.Attempts != tc.wantAttempts {
|
||||
t.Fatalf("attempts %s %+v", calls, session)
|
||||
}
|
||||
if tc.empty && !errors.Is(err, ErrEmptySessionExport) {
|
||||
t.Fatalf("not explicitly empty: %v", err)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user