fix(dispenser): tolerate unusable AP observations during card preparation

This commit is contained in:
2026-09-28 19:43:35 +01:00
parent e26331ffa9
commit b9b2a524dd
8 changed files with 403 additions and 248 deletions
+106 -100
View File
@@ -19,6 +19,7 @@ const (
cmdToEncoder
cmdOutOfMouth
cmdReset
cmdDeliveryClearance
)
type cmdReq struct {
@@ -27,8 +28,6 @@ type cmdReq struct {
respCh chan cmdResp
}
var errDeliveryPending = errors.New("next-card preparation deferred: previous delivery is not clear")
type cmdResp struct {
deliveryPending bool
status []byte
@@ -47,7 +46,7 @@ const (
sequenceTimeout = 32 * time.Second
sequenceUncertainWait = 4 * time.Second
sequenceMaxShakes = 3
deliveryClearanceTimeout = 16 * time.Second
deliveryClearanceTimeout = 6 * time.Second
deliveryMinimumWait = 2 * time.Second
)
@@ -204,18 +203,13 @@ func (c *Client) handle(req cmdReq) {
st, err := c.readWorkerStatus(req.ctx)
req.respCh <- cmdResp{status: st, err: err, deliveryPending: c.deliveryPending}
case cmdDeliveryClearance:
st, err := c.waitWorkerDeliveryClearance(req.ctx)
req.respCh <- cmdResp{status: st, err: err, deliveryPending: c.deliveryPending}
case cmdToEncoder:
if c.deliveryPending {
// Stay inside port ownership: never enqueue a request from the worker.
st, err := c.readWorkerStatus(req.ctx)
if err == nil {
_, err = deliveryClearance(st)
}
if err == nil && c.deliveryPending {
err = errDeliveryPending
log.Debugf("next-card preparation deferred; raw status: % X", st)
}
if err != nil {
if _, err := c.waitWorkerDeliveryClearance(req.ctx); err != nil {
req.respCh <- cmdResp{err: err}
return
}
@@ -405,16 +399,13 @@ func (c *Client) DispenserPrepare(ctx context.Context) (string, error) {
func (c *Client) readSequenceStatus(ctx context.Context, operation string) ([]byte, string, error) {
response := c.doResponse(ctx, cmdStatus)
status, err := response.status, response.err
if err == nil && response.deliveryPending {
err = errDeliveryPending
if err := ctx.Err(); err != nil {
return nil, "", err
}
if err != nil {
if ctxErr := ctx.Err(); ctxErr != nil {
return nil, "", fmt.Errorf("[%s] read status: %w", operation, ctxErr)
}
return nil, "", fmt.Errorf("[%s] read status: %w", operation, err)
if response.deliveryPending {
return c.waitForDeliveryClearance(ctx, operation)
}
status := usableObservation(response.status, response.err, operation)
stockStatus := ""
if len(status) == 4 {
@@ -425,63 +416,85 @@ func (c *Client) readSequenceStatus(ctx context.Context, operation string) ([]by
return status, stockStatus, nil
}
// waitForDeliveryClearance reuses the first clear AP as the initial preparation sample.
// Its bounded window is separate from subsequent preparation and recovery.
func (c *Client) waitForDeliveryClearance(ctx context.Context, operation string) (status []byte, stock string, resultErr error) {
ctx, cancel := context.WithTimeout(ctx, deliveryClearanceTimeout)
// waitWorkerDeliveryClearance runs only inside the serial worker.
// An unusable observation never becomes a fabricated physical position.
func (c *Client) waitWorkerDeliveryClearance(parent context.Context) ([]byte, error) {
ctx, cancel := context.WithTimeout(parent, deliveryClearanceTimeout)
defer cancel()
deadline := c.sequenceTiming.now().Add(deliveryClearanceTimeout)
var lastStatus []byte
defer func() {
if resultErr != nil {
log.Warnf("[%s] delivery clearance stopped: %v; %s raw status: % X", operation, resultErr, statusDescription(lastStatus), lastStatus)
}
}()
deadline := c.now().Add(deliveryClearanceTimeout)
var latest []byte
for {
if err := ctx.Err(); err != nil {
return nil, stock, fmt.Errorf("[%s] delivery clearance: %w", operation, err)
if err := parent.Err(); err != nil {
return nil, err
}
if !c.sequenceTiming.now().Before(deadline) {
return nil, stock, fmt.Errorf("[%s] delivery clearance: %w", operation, context.DeadlineExceeded)
if !c.now().Before(deadline) || ctx.Err() != nil {
class, err := classifyPreparationStatus(latest)
if err == nil && class == positionWellEmpty {
return latest, ErrCardWellEmpty
}
if err == nil && (isPreparationMoving(latest) || latest[1] == 0x34) {
return latest, context.DeadlineExceeded
}
c.deliveryPending = false
log.Warn("delivery clearance assumed after bounded observation fallback")
return latest, nil
}
r := c.doResponse(ctx, cmdStatus)
if len(r.status) > 0 {
lastStatus = r.status
st, err := c.readWorkerStatus(ctx)
if parent.Err() != nil {
return nil, parent.Err()
}
if r.err != nil {
return nil, stock, fmt.Errorf("[%s] delivery clearance status: %w", operation, r.err)
latest = usableObservation(st, err, "delivery clearance")
if latest != nil && latest[3] == 0x38 {
return latest, ErrCardWellEmpty
}
if len(r.status) == 4 {
stock = stockTake(r.status)
c.setStock(r.status)
if !c.deliveryPending {
return latest, nil
}
if err := ctx.Err(); err != nil {
return nil, stock, err
}
if !c.sequenceTiming.now().Before(deadline) {
return nil, stock, fmt.Errorf("[%s] delivery clearance: %w", operation, context.DeadlineExceeded)
}
if !r.deliveryPending {
return r.status, stock, nil
}
if _, err := deliveryClearance(r.status); err != nil {
return nil, stock, fmt.Errorf("[%s] delivery clearance: %w", operation, err)
remaining := deadline.Sub(c.now())
if remaining <= 0 || ctx.Err() != nil {
continue
}
wait := sequencePollInterval
if remaining := deadline.Sub(c.sequenceTiming.now()); remaining < wait {
if remaining < wait {
wait = remaining
}
if err := c.sequenceTiming.wait(ctx, wait); err != nil {
return nil, stock, fmt.Errorf("[%s] delivery clearance: %w", operation, err)
if err := c.sequenceTiming.wait(ctx, wait); err != nil && parent.Err() != nil {
return nil, parent.Err()
}
}
}
// usableObservation preserves strict validation while discarding unusable telemetry.
func usableObservation(status []byte, err error, operation string) []byte {
if err == nil {
_, err = classifyPreparationStatus(status)
}
if err != nil {
log.Warnf("[%s] unusable AP observation; raw status: % X error=%v", operation, status, err)
return nil
}
return status
}
// waitForDeliveryClearance uses a worker request; no worker recursively enqueues.
func (c *Client) waitForDeliveryClearance(ctx context.Context, operation string) ([]byte, string, error) {
r := c.doResponse(ctx, cmdDeliveryClearance)
stock := ""
if len(r.status) == 4 {
stock = stockTake(r.status)
}
if r.err != nil {
return nil, stock, fmt.Errorf("[%s] delivery clearance: %w", operation, r.err)
}
return r.status, stock, nil
}
func (c *Client) prepareCardAtEncoder(parent context.Context, operation string) (stock string, resultErr error) {
status, stock, err := c.waitForDeliveryClearance(parent, operation)
if err != nil {
return stock, err
}
status = usableObservation(status, nil, operation)
started := c.now()
deadline := started.Add(sequenceTimeout)
ctx, cancel := context.WithTimeoutCause(parent, sequenceTimeout, ErrPreparationExhausted)
@@ -502,6 +515,26 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
}
return ctx.Err()
}
// Only observation exhaustion can grant a deadline handoff. Command and
// reset-settle failures never pass through this policy.
observationResult := func(err error) error {
if parent.Err() != nil {
return parent.Err()
}
if !errors.Is(err, ErrPreparationExhausted) || lastFC7.IsZero() {
return err
}
class, _ := classifyPreparationStatus(status)
switch class {
case positionWellEmpty:
return ErrCardWellEmpty
case positionNoCard:
return err
default:
stage = "observation deadline encoder handoff"
return nil
}
}
wait := func(duration time.Duration) error {
if err := checkDeadline(); err != nil {
return err
@@ -535,18 +568,17 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
}
for {
if err := checkDeadline(); err != nil {
return stock, err
}
class, err := classifyPreparationStatus(status)
if err != nil {
return stock, err
return stock, observationResult(err)
}
class, _ := classifyPreparationStatus(status)
// No class means unusable telemetry, sharing the uncertainty timer.
log.Infof("[%s] fresh AP; class=%s previous=%s elapsed=%s shake=%d raw status: % X", operation, class, previous, c.now().Sub(started), shakes, status)
previous = class
switch class {
case encoderConfirmed:
stage = "encoder sensor handoff"
return stock, checkDeadline()
return stock, observationResult(checkDeadline())
case positionWellEmpty:
stage = "empty"
return stock, ErrCardWellEmpty
@@ -583,29 +615,29 @@ func (c *Client) prepareCardAtEncoder(parent context.Context, operation string)
return stock, err
}
} else {
if class == positionUncertain {
if class == positionUncertain || class == "" {
if uncertainSince.IsZero() {
uncertainSince = c.now()
}
if c.now().Sub(uncertainSince) >= sequenceUncertainWait {
stage = "uncertain position handoff"
return stock, checkDeadline()
return stock, observationResult(checkDeadline())
}
} else {
uncertainSince = time.Time{}
}
stage = "polling"
if err := wait(sequencePollInterval); err != nil {
return stock, err
return stock, observationResult(err)
}
}
stage = "fresh AP"
if err := checkDeadline(); err != nil {
return stock, err
return stock, observationResult(err)
}
status, stock, err = c.readSequenceStatus(ctx, operation)
if deadlineErr := checkDeadline(); deadlineErr != nil {
return stock, deadlineErr
return stock, observationResult(deadlineErr)
}
if err != nil {
return stock, err
@@ -628,39 +660,13 @@ func (c *Client) DeliverCurrentCard(ctx context.Context) (string, error) {
return "", nil
}
// BeginPrepareNextCard waits for delivery clearance and dispatches FC7 once,
// without waiting for encoder readiness.
// BeginPrepareNextCard waits for worker-owned clearance and dispatches one FC7.
// It does not wait for encoder readiness.
func (c *Client) BeginPrepareNextCard(ctx context.Context) error {
ctx, cancel := context.WithTimeout(ctx, deliveryClearanceTimeout)
defer cancel()
deadline := c.now().Add(deliveryClearanceTimeout)
for {
if err := ctx.Err(); err != nil {
return err
}
if !c.now().Before(deadline) {
return context.DeadlineExceeded
}
// The worker checks fresh AP while delivery is pending and dispatches
// FC7 only once clear, within the same ownership boundary.
err := c.ToEncoder(ctx)
if !errors.Is(err, errDeliveryPending) {
if err != nil {
return fmt.Errorf("[BeginPrepareNextCard] to encoder: %w", err)
}
return nil
}
wait := sequencePollInterval
if remaining := deadline.Sub(c.now()); remaining < wait {
wait = remaining
}
if wait <= 0 {
return context.DeadlineExceeded
}
if err := c.sequenceTiming.wait(ctx, wait); err != nil {
return err
}
if err := c.ToEncoder(ctx); err != nil {
return fmt.Errorf("[BeginPrepareNextCard] to encoder: %w", err)
}
return nil
}
// PrepareNextCard runs the same bounded physical preparation for a later issuance attempt.