feat(dispenser): recover K720 card position during uncertain encoding

This commit is contained in:
2026-10-22 18:56:22 +01:00
parent 28aea4aab2
commit 8c5e61efd0
6 changed files with 472 additions and 20 deletions
+112 -17
View File
@@ -545,10 +545,24 @@ func (c *Client) waitForDeliveryClearance(ctx context.Context, operation string)
return r.status, stock, nil
}
func (c *Client) prepareCardAtEncoder(parent context.Context, operation string) (stock string, resultErr error) {
// PreparationResult carries this issuance attempt's handoff and recovery budget.
type PreparationResult struct {
Stock string
UncertainHandoff bool
ShakesUsed int
lastFC7 time.Time
}
func (c *Client) prepareCardAtEncoder(ctx context.Context, operation string) (string, error) {
preparation, err := c.prepareCardForEncoding(ctx, operation)
return preparation.Stock, err
}
func (c *Client) prepareCardForEncoding(parent context.Context, operation string) (preparation PreparationResult, resultErr error) {
status, stock, err := c.waitForDeliveryClearance(parent, operation)
preparation.Stock = stock
if err != nil {
return stock, err
return preparation, err
}
status = usableObservation(status, nil, operation)
started := c.now()
@@ -560,6 +574,13 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
var lastFC7, uncertainSince time.Time
var previous preparationClass
defer func() {
preparation.Stock = stock
preparation.ShakesUsed = shakes
preparation.lastFC7 = lastFC7
if resultErr == nil && !lastFC7.IsZero() {
class, _ := classifyPreparationStatus(status)
preparation.UncertainHandoff = class != encoderConfirmed
}
log.Infof("[%s] preparation finished; stage=%s shakes=%d elapsed=%s raw status: % X error=%v", operation, stage, shakes, c.now().Sub(started), status, resultErr)
}()
checkDeadline := func() error {
@@ -624,7 +645,7 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
}
for {
if err := checkDeadline(); err != nil {
return stock, observationResult(err)
return preparation, observationResult(err)
}
class, _ := classifyPreparationStatus(status)
// No class means unusable telemetry, sharing the uncertainty timer.
@@ -634,41 +655,41 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
switch class {
case encoderConfirmed:
stage = "encoder sensor handoff"
return stock, observationResult(checkDeadline())
return preparation, observationResult(checkDeadline())
case positionWellEmpty:
stage = "empty"
return stock, ErrCardWellEmpty
return preparation, ErrCardWellEmpty
}
if lastFC7.IsZero() {
if err := sendFC7(); err != nil {
return stock, err
return preparation, err
}
} else if class == positionNoCard && c.now().Sub(lastFC7) >= sequenceShakeAfter {
uncertainSince = time.Time{}
if shakes == sequenceMaxShakes {
stage = "three shakes exhausted"
return stock, ErrPreparationExhausted
return preparation, ErrPreparationExhausted
}
shakes++
stage = "RS dispatch"
if err := checkDeadline(); err != nil {
return stock, err
return preparation, err
}
err := c.Reset(ctx)
if deadlineErr := checkDeadline(); deadlineErr != nil {
return stock, deadlineErr
return preparation, deadlineErr
}
if err != nil {
return stock, fmt.Errorf("[%s] RS dispatch: %w", operation, err)
return preparation, fmt.Errorf("[%s] RS dispatch: %w", operation, err)
}
stage = "reset settling"
log.Infof("[%s] RS dispatched; shake=%d settling=%s", operation, shakes, sequenceResetWait)
if err := wait(sequenceResetWait); err != nil {
return stock, err
return preparation, err
}
log.Infof("[%s] reset settle wait completed; shake=%d", operation, shakes)
if err := sendFC7(); err != nil {
return stock, err
return preparation, err
}
} else {
if class == positionUncertain || class == "" {
@@ -677,26 +698,26 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
}
if c.now().Sub(uncertainSince) >= sequenceUncertainWait {
stage = "uncertain position handoff"
return stock, observationResult(checkDeadline())
return preparation, observationResult(checkDeadline())
}
} else {
uncertainSince = time.Time{}
}
stage = "polling"
if err := wait(sequencePollInterval); err != nil {
return stock, observationResult(err)
return preparation, observationResult(err)
}
}
stage = "fresh AP"
if err := checkDeadline(); err != nil {
return stock, observationResult(err)
return preparation, observationResult(err)
}
status, stock, err = c.readSequenceStatus(ctx, operation)
if deadlineErr := checkDeadline(); deadlineErr != nil {
return stock, observationResult(deadlineErr)
return preparation, observationResult(deadlineErr)
}
if err != nil {
return stock, err
return preparation, err
}
}
}
@@ -706,6 +727,80 @@ func (c *Client) PrepareCurrentCard(ctx context.Context) (string, error) {
return c.prepareCardAtEncoder(ctx, "PrepareCurrentCard")
}
// PrepareCurrentCardForEncoding preserves preparation while exposing uncertain handoff.
func (c *Client) PrepareCurrentCardForEncoding(ctx context.Context) (PreparationResult, error) {
return c.prepareCardForEncoding(ctx, "PrepareCurrentCard")
}
// RecoverCurrentCard spends only the remaining issuance budget during encoding.
// It must be cancelled and joined before delivery; all commands use the serial worker.
func (c *Client) RecoverCurrentCard(ctx context.Context, preparation PreparationResult) (resultErr error) {
if !preparation.UncertainHandoff {
return nil
}
const operation = "uncertain encoding recovery"
started := c.now()
shakes, lastFC7 := preparation.ShakesUsed, preparation.lastFC7
reason := "recovery error"
defer func() {
if ctx.Err() != nil {
reason = context.Cause(ctx).Error()
}
log.Infof("[%s] stopped; reason=%s shakes=%d remaining=%d elapsed=%s error=%v", operation, reason, shakes, sequenceMaxShakes-shakes, c.now().Sub(started), resultErr)
}()
log.Infof("[%s] started; shakes=%d remaining=%d", operation, shakes, sequenceMaxShakes-shakes)
observe := func() (bool, error) {
status, _, err := c.readSequenceStatus(ctx, operation)
if err != nil {
return true, err
}
class, _ := classifyPreparationStatus(status)
log.Infof("[%s] fresh AP; class=%s shakes=%d remaining=%d raw status: % X", operation, class, shakes, sequenceMaxShakes-shakes, status)
switch class {
case encoderConfirmed:
reason = "encoder confirmed"
return true, nil
case positionWellEmpty:
reason = "card well empty"
return true, ErrCardWellEmpty
default:
return false, nil
}
}
for {
if stopped, err := observe(); stopped {
return err
}
if shakes >= sequenceMaxShakes {
reason = "shake budget exhausted"
return nil
}
if remaining := sequenceShakeAfter - c.now().Sub(lastFC7); remaining > 0 {
if err := c.sequenceTiming.wait(ctx, min(sequencePollInterval, remaining)); err != nil {
return err
}
continue
}
shakes++
log.Infof("[%s] RS attempt; shake=%d remaining=%d", operation, shakes, sequenceMaxShakes-shakes)
if err := c.Reset(ctx); err != nil {
return fmt.Errorf("[%s] RS dispatch: %w", operation, err)
}
if err := c.sequenceTiming.wait(ctx, sequenceResetWait); err != nil {
return err
}
// A diagnostic AP cannot turn unusable telemetry into a fatal error.
if stopped, err := observe(); stopped {
return err
}
log.Infof("[%s] FC7 attempt; shake=%d remaining=%d", operation, shakes, sequenceMaxShakes-shakes)
if err := c.ToEncoder(ctx); err != nil {
return fmt.Errorf("[%s] FC7 dispatch: %w", operation, err)
}
lastFC7 = c.now()
}
}
// DeliverCurrentCard presents the encoded card and confirms command acceptance.
func (c *Client) DeliverCurrentCard(ctx context.Context) (string, error) {
const operation = "DeliverCurrentCard"
+148
View File
@@ -112,6 +112,154 @@ func TestResetPacket(t *testing.T) {
}
}
func TestUncertainRecoveryContinuesPreparationBudget(t *testing.T) {
responses := append(positionResponses(0x30, 5), positionResponses(0x35, 5)...)
responses = append(responses, cmdResp{status: status(0x35)}, cmdResp{err: errors.New("unusable diagnostic AP")})
responses = append(responses, positionResponses(0x30, 4)...)
responses = append(responses, cmdResp{status: status(0x35)}, cmdResp{status: status(0x37)})
c, d := newSequenceTestClient(t, responses...)
preparation, err := c.PrepareCurrentCardForEncoding(context.Background())
if err != nil || !preparation.UncertainHandoff || preparation.ShakesUsed != 1 {
t.Fatalf("preparation=%+v error=%v, want uncertain handoff after one shake", preparation, err)
}
before := len(d.commands)
if err := c.RecoverCurrentCard(context.Background(), preparation); err != nil {
t.Fatal(err)
}
want := []cmdType{cmdStatus, cmdReset, cmdStatus, cmdToEncoder, cmdStatus, cmdStatus, cmdStatus, cmdStatus, cmdReset, cmdStatus, cmdToEncoder, cmdStatus}
if !reflect.DeepEqual(d.commands[before:], want) {
t.Errorf("recovery commands=%v, want %v", d.commands[before:], want)
}
if commandCount(d.commands, cmdReset) != 3 || commandCount(d.commands, cmdToEncoder) != 4 {
t.Errorf("whole issuance commands=%v, want three RS and four FC7", d.commands)
}
for i := before; i < len(d.commands); i++ {
if d.commands[i] == cmdToEncoder && d.commandTimes[i].Sub(d.commandTimes[i-2]) != sequenceResetWait {
t.Errorf("recovery FC7 at %d did not follow RS, settle and diagnostic AP: %v", i, d.commands)
}
}
}
func TestUncertainRecoveryProductionTrace(t *testing.T) {
responses := []cmdResp{{status: status(0x30)}}
for i := 0; i < 5; i++ {
responses = append(responses, cmdResp{err: errors.New("AP unavailable")})
}
responses = append(responses, cmdResp{status: status(0x35)}, cmdResp{status: status(0x35)}, cmdResp{status: status(0x37)})
c, d := newSequenceTestClient(t, responses...)
preparation, err := c.PrepareCurrentCardForEncoding(context.Background())
if err != nil || !preparation.UncertainHandoff || preparation.ShakesUsed != 0 {
t.Fatalf("production trace preparation=%+v error=%v, want uncertain handoff with unused budget", preparation, err)
}
if err := c.RecoverCurrentCard(context.Background(), preparation); err != nil {
t.Fatal(err)
}
if commandCount(d.commands, cmdReset) != 1 || commandCount(d.commands, cmdToEncoder) != 2 {
t.Errorf("production trace commands=%v, want one shake after initial FC7", d.commands)
}
}
func TestUncertainRecoveryStopsAtPhysicalPosition(t *testing.T) {
for _, position := range []byte{0x32, 0x33, 0x37, 0x3F, 0x38} {
for _, afterReset := range []bool{false, true} {
t.Run(fmt.Sprintf("position=%X afterReset=%t", position, afterReset), func(t *testing.T) {
responses := []cmdResp{{status: status(position)}}
if afterReset {
responses = append([]cmdResp{{status: status(0x35)}}, responses...)
}
c, d := newSequenceTestClient(t, responses...)
err := c.RecoverCurrentCard(context.Background(), PreparationResult{UncertainHandoff: true})
var wantErr error
if position == 0x38 {
wantErr = ErrCardWellEmpty
}
wantRS := 0
if afterReset {
wantRS = 1
}
if !errors.Is(err, wantErr) || commandCount(d.commands, cmdReset) != wantRS || commandCount(d.commands, cmdToEncoder) != 0 {
t.Errorf("position %X recovery error=%v commands=%v, want error=%v RS=%d FC7=0", position, err, d.commands, wantErr, wantRS)
}
})
}
}
}
func TestUncertainRecoveryExhaustsOnlyRemainingShakes(t *testing.T) {
for used := 0; used <= sequenceMaxShakes; used++ {
t.Run(fmt.Sprint(used), func(t *testing.T) {
c, d := newSequenceTestClient(t, positionResponses(0x35, 30)...)
preparation := PreparationResult{UncertainHandoff: true, ShakesUsed: used, lastFC7: c.now().Add(-sequenceShakeAfter)}
if err := c.RecoverCurrentCard(context.Background(), preparation); err != nil {
t.Fatal(err)
}
want := sequenceMaxShakes - used
if commandCount(d.commands, cmdReset) != want || commandCount(d.commands, cmdToEncoder) != want {
t.Errorf("used=%d commands=%v, want %d RS/FC7", used, d.commands, want)
}
})
}
}
func TestUncertainRecoveryPreservesFC7ObservationDelay(t *testing.T) {
c, d := newSequenceTestClient(t, positionResponses(0x35, 4)...)
d.statusResponses = append(d.statusResponses, cmdResp{status: status(0x37)})
started := c.now()
if err := c.RecoverCurrentCard(context.Background(), PreparationResult{UncertainHandoff: true, lastFC7: started}); err != nil {
t.Fatal(err)
}
if commandCount(d.commands, cmdReset) != 1 || d.commandTimes[4].Sub(started) != sequenceShakeAfter {
t.Errorf("commands=%v times=%v, want first RS after three seconds", d.commands, d.commandTimes)
}
}
func TestUncertainRecoveryCommandFailuresAndCancellation(t *testing.T) {
for _, command := range []cmdType{cmdReset, cmdToEncoder} {
c, d := newSequenceTestClient(t, positionResponses(0x35, 3)...)
failure := errors.New("recovery dispatch failed")
d.commandErrors[command] = []error{failure}
if err := c.RecoverCurrentCard(context.Background(), PreparationResult{UncertainHandoff: true}); !errors.Is(err, failure) {
t.Errorf("command=%v error=%v, want %v", command, err, failure)
}
if commandCount(d.commands, command) != 1 {
t.Errorf("failed command=%v commands=%v, want one attempt", command, d.commands)
}
}
c, d := newSequenceTestClient(t, cmdResp{status: status(0x35)})
ctx, cancel := context.WithCancel(context.Background())
t.Cleanup(cancel)
c.sequenceTiming.wait = func(ctx context.Context, duration time.Duration) error {
if duration != sequenceResetWait {
t.Errorf("wait=%s, want reset settle", duration)
}
cancel()
return ctx.Err()
}
if err := c.RecoverCurrentCard(ctx, PreparationResult{UncertainHandoff: true}); !errors.Is(err, context.Canceled) {
t.Errorf("settle cancellation=%v, want context.Canceled", err)
}
if !reflect.DeepEqual(d.commands, []cmdType{cmdStatus, cmdReset}) {
t.Errorf("cancelled commands=%v, want AP/RS only", d.commands)
}
if err := c.RecoverCurrentCard(ctx, PreparationResult{UncertainHandoff: true}); !errors.Is(err, context.Canceled) {
t.Errorf("already cancelled recovery=%v, want context.Canceled", err)
}
}
func TestConfirmedPreparationNeverRecovers(t *testing.T) {
c, d := newSequenceTestClient(t, cmdResp{status: status(0x37)})
preparation, err := c.PrepareCurrentCardForEncoding(context.Background())
if err != nil || preparation.UncertainHandoff {
t.Fatalf("confirmed preparation=%+v error=%v", preparation, err)
}
if err := c.RecoverCurrentCard(context.Background(), preparation); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(d.commands, []cmdType{cmdStatus}) {
t.Errorf("confirmed commands=%v, want initial AP only", d.commands)
}
}
func TestDeliverCurrentCardSucceedsAfterCommandAcceptanceWithoutStatusPolling(t *testing.T) {
staleStatus := []byte{0x30, 0x32, 0x32, 0x33}
client, device := newSequenceTestClient(t, cmdResp{status: staleStatus})