package handlers import ( "context" "encoding/json" "errors" "io" "net/http" "net/http/httptest" "os" "reflect" "strings" "testing" "time" "gitea.futuresens.co.uk/futuresens/cmstypes" "gitea.futuresens.co.uk/futuresens/hardlink/v2/config" "gitea.futuresens.co.uk/futuresens/hardlink/v2/internal/creditcall" "gitea.futuresens.co.uk/futuresens/hardlink/v2/internal/types" "gitea.futuresens.co.uk/futuresens/hardlink/v2/paymentapi" ) // This contract list is independent of the production allowlist. var creditCallDiagnosticSDKFixtures = []string{ "ChipCardRemoved", "ClientNotConnectedToServer", "NoPinPadsAvailable", "AmountTooLarge", "AmountTooSmall", "NoPinPadsConfigured", "PaymentDeviceUnavailable", "PaymentDeviceNotInitialized", "PinpadConnectionClosed", "PinPadTransactionTerminated", "EposTransactionTerminated", "TransactionProcessingError", "TransactionInProgress", "TransactionAlreadyInProgressError", "TransactionNotStarted", "MissingParameter", "InvalidParameter", "InvalidValue", "UnexpectedParameters", "AmountZeroNotAllowed", "AmountInvalid", "AmountMissing", "ReferenceAlreadyExistsForApprovedTransaction", "PinPadAmountInvalid", "PinpadAmountTooLarge", "TransactionReferenceMissing", "TransactionReferenceEmpty", "TransactionForConfirmVoidNotFound", "TransactionNotFound", "TransactionAlreadyConfirmed", "TransactionOriginallyDeclined", "TransactionNotCommitted", "ConfirmRequestFailed", "ConfirmAccountVerificationNotAllowed", "ConfirmLinkedRefundNotAllowed", "RemoteServerAccessFailed", "ServerCommunicationError", "ServerRequestError", "ServerResponseError", "NoResponseFromServer", "TemporarilyUnavailable", "ChipCardBlocked", "ChipReadFailure", "SwipeReadFailure", "ExpiredCard", "BadCard", "CardSchemeNotSupported", "CardUsageExceeded", "PinPadUserCancelled", "CardHolderActionTimedOut", } type creditCallDiagnosticFixture struct { name, operation string initial, confirmation map[string]string startFailure, confirmFailure string confirmationXML string recoverConfirmation bool zero bool reason, message string } func creditCallDiagnosticFields(result, sdkError string) map[string]string { return map[string]string{ types.TransactionResult: result, types.Errors: sdkError, types.TransactionType: "SALE", types.Reference: "SYNTH-STAGE2", types.TotalAmount: "1234", types.ReceiptDataCardholder: "synthetic initial receipt", types.CardType: "Visa", types.PanMasked: "************1133", types.ExpiryDate: "1230", types.CardHash: "synthetic-hash", types.CardReference: "synthetic-card-reference", } } func creditCallDiagnosticFixtures() []creditCallDiagnosticFixture { var fixtures []creditCallDiagnosticFixture for _, operation := range []string{"sale", "preauth"} { for _, result := range []string{"ERROR", "DECLINED", "UNKNOWN", "CANCELLED", "TIMEOUT", "", "APPROVED"} { for _, code := range creditCallDiagnosticSDKFixtures { fixture := creditCallDiagnosticFixture{ name: operation + "/initial_" + result + "/" + code, operation: operation, initial: creditCallDiagnosticFields(result, code), reason: "sdk_" + code, message: "Payment outcome uncertain: " + code + "; contact reception", } switch result { case "APPROVED": fixture.reason, fixture.message = "", "Payment approved" case "TIMEOUT": fixture.reason, fixture.message = "cli_timeout", "Payment outcome uncertain: CLI wait expired; contact reception" case "DECLINED": fixture.message = "Transaction declined: " + code case "CANCELLED": fixture.message = "Transaction cancelled: " + code } if result == "" || result == "ERROR" || result == "DECLINED" { if code == "PinPadUserCancelled" { fixture.reason, fixture.message = "user_cancelled", "Transaction cancelled" } if code == "CardHolderActionTimedOut" { fixture.reason, fixture.message = "cardholder_timeout", "Cardholder action timed out" } } fixtures = append(fixtures, fixture) } } for _, result := range []string{"ERROR", "DECLINED", "UNKNOWN", "CANCELLED", "TIMEOUT", ""} { for _, unknown := range []struct{ name, code string }{ {"absent", ""}, {"unrecognized", "DeviceUnavailable"}, {"issuer", "InsufficientFunds"}, {"numeric", "500005"}, {"compound", "ChipCardRemoved,AmountTooSmall"}, {"whitespace", " ChipCardRemoved"}, {"case", "chipcardremoved"}, {"secret", "token=SYNTHETIC-SECRET; PAN=4111111111111111"}, } { fixture := creditCallDiagnosticFixture{name: operation + "/fallback_" + result + "/" + unknown.name, operation: operation, initial: creditCallDiagnosticFields(result, unknown.code), message: "Payment outcome uncertain; contact reception"} fixture.initial[types.ErrorDescription] = "ChipCardRemoved SYNTHETIC-SECRET" switch result { case "DECLINED": fixture.message = "Transaction declined" case "CANCELLED": fixture.message = "Transaction cancelled" case "TIMEOUT": fixture.reason, fixture.message = "cli_timeout", "Payment outcome uncertain: CLI wait expired; contact reception" } fixtures = append(fixtures, fixture) } } for _, failure := range []string{"transport", "incomplete", "malformed", "error_frame", "unknown_frame"} { fixtures = append(fixtures, creditCallDiagnosticFixture{name: operation + "/start/" + failure, operation: operation, initial: creditCallDiagnosticFields("ERROR", "ChipCardRemoved"), startFailure: failure, message: "Payment outcome uncertain; contact reception"}) } missing := creditCallDiagnosticFields("ERROR", "AmountTooSmall") delete(missing, types.TransactionResult) fixtures = append(fixtures, creditCallDiagnosticFixture{name: operation + "/missing_result", operation: operation, initial: missing, reason: "sdk_AmountTooSmall", message: "Payment outcome uncertain: AmountTooSmall; contact reception"}) } for _, code := range creditCallDiagnosticSDKFixtures { fixtures = append(fixtures, creditCallDiagnosticFixture{name: "sale/confirmation_sdk/" + code, operation: "sale", initial: creditCallDiagnosticFields("APPROVED", "AmountTooLarge"), confirmation: map[string]string{types.TransactionResult: "ERROR", types.Errors: code, types.ReceiptDataCardholder: "synthetic confirmation receipt"}, reason: "confirmation_sdk_" + code, message: "Payment outcome uncertain: ConfirmTransaction: " + code + "; contact reception"}) } for _, result := range []string{"DECLINED", "CANCELLED", "CANCELED", "ERROR", "TIMEOUT", "UNKNOWN", ""} { suffix := strings.ToLower(result) if suffix == "canceled" { suffix = "cancelled" } if suffix == "" || suffix == "unknown" { suffix = "unknown" } fixtures = append(fixtures, creditCallDiagnosticFixture{name: "sale/confirmation_result/" + result, operation: "sale", initial: creditCallDiagnosticFields("APPROVED", "ChipCardRemoved"), confirmation: map[string]string{types.TransactionResult: result}, reason: "confirmation_result_" + suffix, message: "Payment outcome uncertain: ConfirmTransaction result " + suffix + "; contact reception"}) } for _, failure := range []struct{ name, reason, cause string }{ {"deadline", "confirmation_timeout", "ConfirmTransaction timed out"}, {"timeout", "confirmation_timeout", "ConfirmTransaction timed out"}, {"request", "confirmation_request_error", "ConfirmTransaction request failed"}, {"read", "confirmation_response_read_error", "ConfirmTransaction response could not be read"}, } { fixtures = append(fixtures, creditCallDiagnosticFixture{name: "sale/confirmation_failure/" + failure.name, operation: "sale", initial: creditCallDiagnosticFields("APPROVED", ""), confirmFailure: failure.name, reason: failure.reason, message: "Payment outcome uncertain: " + failure.cause + "; contact reception"}) } for _, failure := range []string{"request", "read"} { fixtures = append(fixtures, creditCallDiagnosticFixture{name: "sale/confirmation_recovers/" + failure, operation: "sale", initial: creditCallDiagnosticFields("APPROVED", ""), confirmFailure: failure, recoverConfirmation: true, message: "Payment approved"}) } for _, response := range []struct{ name, xml, reason, cause string }{ {"omitted", "", "", ""}, {"malformed_retains_approval", "", "", ""}, {"malformed_after_error", "TRANSACTION_RESULTERROR", "confirmation_invalid_response", "ConfirmTransaction response is invalid"}, } { message := "Payment approved" if response.reason != "" { message = "Payment outcome uncertain: " + response.cause + "; contact reception" } fixtures = append(fixtures, creditCallDiagnosticFixture{name: "sale/confirmation_xml/" + response.name, operation: "sale", initial: creditCallDiagnosticFields("APPROVED", "ChipCardRemoved"), confirmationXML: response.xml, reason: response.reason, message: message}) } for _, code := range []string{"ConfirmTransaction failed: SYNTHETIC-SECRET PAN=4111111111111111", "ChipCardRemoved,SYNTHETIC-SECRET", "500005", "chipcardremoved"} { reason, cause := "confirmation_result_error", "ConfirmTransaction result error" name := "fallback_" + code if strings.HasPrefix(code, "ConfirmTransaction failed:") { reason, cause, name = "confirmation_cli_error", "ConfirmTransaction CLI failed", "cli_exception" } fixtures = append(fixtures, creditCallDiagnosticFixture{name: "sale/" + name, operation: "sale", initial: creditCallDiagnosticFields("APPROVED", ""), confirmation: map[string]string{types.TransactionResult: "ERROR", types.Errors: code}, reason: reason, message: "Payment outcome uncertain: " + cause + "; contact reception"}) } for _, result := range []string{"APPROVED", "ERROR"} { fields := creditCallDiagnosticFields(result, "ChipCardRemoved") fields[types.TransactionType], fields[types.TotalAmount] = "ACCOUNT VERIFICATION", "" reason, message := "sdk_ChipCardRemoved", "Payment outcome uncertain: ChipCardRemoved; contact reception" if result == "APPROVED" { reason, message = "", "Payment approved" } fixtures = append(fixtures, creditCallDiagnosticFixture{name: "preauth/verification/" + result, operation: "preauth", initial: fields, zero: true, reason: reason, message: message}) } fields := creditCallDiagnosticFields("APPROVED", "ChipCardRemoved") fields[types.TransactionType] = "Refund" fixtures = append(fixtures, creditCallDiagnosticFixture{name: "preauth/unrecognized_approved_type", operation: "preauth", initial: fields, message: "Payment outcome uncertain; contact reception"}) for _, operation := range []string{"sale", "preauth"} { fields := creditCallDiagnosticFields("APPROVED", "ChipCardRemoved") fields[types.TotalAmount], fields[types.TransactionType] = "invalid", "ACCOUNT VERIFICATION" fixtures = append(fixtures, creditCallDiagnosticFixture{name: operation + "/amount_unverified", operation: operation, initial: fields, reason: "amount_unverified", message: "Payment amount uncertain; contact reception"}) } return fixtures } type creditCallDiagnosticRequest struct { Method, Path, Body string FreshCallDeadline bool } type creditCallDiagnosticObservation struct { HTTPStatus int Final *paymentapi.Result `json:",omitempty"` Legacy *cmstypes.ResponseRec `json:",omitempty"` Progress []string Requests []creditCallDiagnosticRequest Receipts []string Persistence map[string]any PersistenceCount int32 PersistenceTimeValid bool BodiesClosed []bool RetryDelayKept bool } type creditCallDiagnosticBody struct { io.Reader err error closed bool } func (b *creditCallDiagnosticBody) Read(p []byte) (int, error) { if b.err != nil { return 0, b.err } return b.Reader.Read(p) } func (b *creditCallDiagnosticBody) Close() error { b.closed = true; return nil } type creditCallDiagnosticTimeout struct{} func (creditCallDiagnosticTimeout) Error() string { return "SYNTHETIC-SECRET timeout" } func (creditCallDiagnosticTimeout) Timeout() bool { return true } func (creditCallDiagnosticTimeout) Temporary() bool { return true } func captureCreditCallDiagnostic(t *testing.T, fixture creditCallDiagnosticFixture, legacy bool) creditCallDiagnosticObservation { t.Helper() started := time.Now() observation := creditCallDiagnosticObservation{RetryDelayKept: true} app := &App{isPayment: true, cfg: &config.ConfigRec{TimeoutSeconds: 1}, creditCallReceipt: func(receipt string) { observation.Receipts = append(observation.Receipts, receipt) }} database := preauthTestDatabase(t, app) var bodies []*creditCallDiagnosticBody var confirmations []time.Time app.creditCallTransport = creditCallRoundTrip(func(r *http.Request) (*http.Response, error) { payload, err := io.ReadAll(r.Body) if err != nil { t.Errorf("read synthetic %s request: %v", fixture.name, err) } deadline, ok := r.Context().Deadline() observation.Requests = append(observation.Requests, creditCallDiagnosticRequest{r.Method, r.URL.Path, string(payload), ok && time.Until(deadline) > 299*time.Second}) body := &creditCallDiagnosticBody{} if r.URL.Path == "/confirm-transaction/" { confirmations = append(confirmations, time.Now()) failure := fixture.confirmFailure if fixture.recoverConfirmation && len(confirmations) > 1 { failure = "" } switch failure { case "deadline": return nil, context.DeadlineExceeded case "timeout": return nil, creditCallDiagnosticTimeout{} case "request": return nil, errors.New("SYNTHETIC-SECRET request failure") case "read": body.err = errors.New("SYNTHETIC-SECRET body failure") } fields := fixture.confirmation if fields == nil { fields = map[string]string{types.TransactionResult: "APPROVED", types.ReceiptDataCardholder: "synthetic confirmation receipt"} } xmlBody := fixture.confirmationXML if xmlBody == "" { xmlBody = chipDNAFixture(t, fields) } body.Reader = strings.NewReader(xmlBody) } else { if fixture.startFailure == "transport" { return nil, errors.New("SYNTHETIC-SECRET start failure") } if legacy { body.Reader = strings.NewReader(chipDNAFixture(t, fixture.initial)) } else { frame, err := json.Marshal(map[string]any{"type": "result", "result": fixture.initial}) if err != nil { t.Errorf("marshal synthetic %s frame: %v", fixture.name, err) } wire := string(frame) + "\n" switch fixture.startFailure { case "incomplete": wire = string(frame) case "malformed": wire = "{SYNTHETIC-SECRET\n" case "error_frame": wire = "{\"type\":\"error\",\"message\":\"SYNTHETIC-SECRET\"}\n" case "unknown_frame": wire = "{\"type\":\"SYNTHETIC-SECRET\"}\n" } body.Reader = strings.NewReader("{\"type\":\"status\",\"source\":\"UPDATE\",\"value\":\"CardRequested\"}\n" + wire) } } bodies = append(bodies, body) // Confirmation HTTP status remains ignored when its body is readable. status := http.StatusOK if r.URL.Path == "/confirm-transaction/" { status = http.StatusServiceUnavailable } return &http.Response{StatusCode: status, Body: body, Header: make(http.Header)}, nil }) app.EnableCreditCallStreaming() recorder := httptest.NewRecorder() amount := "1234" if fixture.zero { amount = "0" } if legacy { if fixture.operation == "preauth" { app.takePreauthorization(recorder, preauthLegacyRequest(amount, "Sale", "2030-01-02 00:00:00 +0000")) } else { app.takePayment(recorder, saleRequest(false)) } observation.Legacy = &cmstypes.ResponseRec{} if err := json.Unmarshal(recorder.Body.Bytes(), observation.Legacy); err != nil { t.Fatalf("decode %s legacy result: %v", fixture.name, err) } } else { request := httptest.NewRequest(http.MethodPost, "/api/payment/"+fixture.operation, strings.NewReader(`{"reference":"SYNTH-STAGE2","amount":`+amount+`,"currency":"GBP","checkoutDate":"2030-01-02 00:00:00 +0000"}`)) request.Header.Set("Content-Type", "application/json") app.streamPayment(recorder, request, fixture.operation == "preauth") for _, frame := range decodePaymentStream(t, recorder.Body) { if frame.Result != nil { if observation.Final != nil { t.Errorf("%s emitted multiple final results", fixture.name) } observation.Final = frame.Result } else { observation.Progress = append(observation.Progress, frame.Code) } } if observation.Final == nil { t.Fatalf("%s emitted no final result", fixture.name) } for _, secret := range []string{"SYNTHETIC-SECRET", "4111111111111111", " 1 { observation.RetryDelayKept = confirmations[1].Sub(confirmations[0]) >= 2*time.Second } if !observation.RetryDelayKept { t.Errorf("%s confirmation retry delay was shorter than two seconds", fixture.name) } return observation } // This test uses only pre-existing interfaces, so the same fixtures run against // the captured unmodified production source and the diagnostic implementation. func TestCreditCallDiagnosticParityCapture(t *testing.T) { observations := map[string]creditCallDiagnosticObservation{} for _, fixture := range creditCallDiagnosticFixtures() { t.Run(fixture.name, func(t *testing.T) { observations[fixture.name] = captureCreditCallDiagnostic(t, fixture, false) }) } // Legacy responses and side effects must remain exactly unchanged too. for _, fixture := range creditCallDiagnosticFixtures() { if fixture.startFailure != "" || fixture.zero || fixture.confirmFailure != "" { continue } t.Run("legacy/"+fixture.name, func(t *testing.T) { observations["legacy/"+fixture.name] = captureCreditCallDiagnostic(t, fixture, true) }) } if baseline := os.Getenv("HARDLINK_CREDITCALL_DIAGNOSTIC_BASELINE"); baseline != "" { data, err := os.ReadFile(baseline) if err != nil { t.Fatal(err) } var before map[string]creditCallDiagnosticObservation if err := json.Unmarshal(data, &before); err != nil { t.Fatal(err) } // Round-trip current observations to match interface-valued SQL argument types. data, err = json.Marshal(observations) if err != nil { t.Fatal(err) } var after map[string]creditCallDiagnosticObservation if err := json.Unmarshal(data, &after); err != nil { t.Fatal(err) } if len(before) != len(after) { t.Errorf("capture cases=%d, want baseline %d", len(after), len(before)) } for name, want := range before { got, ok := after[name] if !ok { t.Errorf("missing baseline fixture %q", name) continue } if want.Final != nil && got.Final != nil { want.Final.Reason, want.Final.Message = "", "" got.Final.Reason, got.Final.Message = "", "" } // SQL generates the transaction timestamp during each run. Its type, // UTC location and range are asserted above; retain raw values in captures. if want.Persistence != nil && got.Persistence != nil { want.Persistence["TxnDateTime"], got.Persistence["TxnDateTime"] = "validated current UTC time", "validated current UTC time" } if !reflect.DeepEqual(got, want) { t.Errorf("%s changed beyond diagnostic fields: got %+v, want %+v", name, got, want) } } } if destination := os.Getenv("HARDLINK_CREDITCALL_DIAGNOSTIC_CAPTURE"); destination != "" { data, err := json.MarshalIndent(observations, "", " ") if err != nil { t.Fatal(err) } if err := os.WriteFile(destination, data, 0600); err != nil { t.Fatal(err) } } } func TestCreditCallDiagnosticReasons(t *testing.T) { for _, fixture := range creditCallDiagnosticFixtures() { t.Run(fixture.name, func(t *testing.T) { got := captureCreditCallDiagnostic(t, fixture, false).Final if got.Reason != fixture.reason || got.Message != fixture.message { t.Errorf("%s Reason/Message=%q/%q, want %q/%q", fixture.name, got.Reason, got.Message, fixture.reason, fixture.message) } if strings.HasPrefix(got.Reason, "confirmation_") && (got.Outcome != "unknown" || got.Retryable) { t.Errorf("%s final=%+v, want nonretryable confirmation uncertainty", fixture.name, got) } }) } } func TestCreditCallDiagnosticEntryOrderAndOwnership(t *testing.T) { for _, fixture := range []struct { name string entries []creditcall.EntryXML want creditCallDiagnostic }{ {name: "last error unrecognized", entries: []creditcall.EntryXML{ {Key: types.Errors, Value: "ChipCardRemoved"}, {Key: types.Errors, Value: "DeviceUnavailable"}, }}, {name: "last error recognized", entries: []creditcall.EntryXML{ {Key: types.Errors, Value: "DeviceUnavailable"}, {Key: types.Errors, Value: "ChipCardRemoved"}, }, want: creditCallDiagnostic{reason: "sdk_ChipCardRemoved", cause: "ChipCardRemoved"}}, {name: "last result approved", entries: []creditcall.EntryXML{ {Key: types.TransactionResult, Value: "ERROR"}, {Key: types.Errors, Value: "ChipCardRemoved"}, {Key: types.TransactionResult, Value: "APPROVED"}, }}, } { t.Run(fixture.name, func(t *testing.T) { before := append([]creditcall.EntryXML(nil), fixture.entries...) got := creditCallInitialDiagnostic(creditcall.TransactionResultXML{Entries: fixture.entries}) if got != fixture.want { t.Errorf("creditCallInitialDiagnostic(%+v)=%+v, want %+v", fixture.entries, got, fixture.want) } if !reflect.DeepEqual(fixture.entries, before) { t.Errorf("creditCallInitialDiagnostic changed entries: got %+v, want %+v", fixture.entries, before) } }) } } func TestCreditCallConfirmationSDKErrorWithoutResultKeepsLegacyApproval(t *testing.T) { fixture := creditCallDiagnosticFixture{name: "sale/confirmation_sdk_without_result", operation: "sale", initial: creditCallDiagnosticFields("APPROVED", ""), confirmation: map[string]string{types.Errors: "TransactionNotFound"}} got := captureCreditCallDiagnostic(t, fixture, false) if got.Final.Outcome != "approved" || got.Final.Reason != "" || got.Final.TransactionReference != "SYNTH-STAGE2" || got.Final.AmountMinor != 1234 { t.Errorf("confirmation SDK error without TRANSACTION_RESULT final=%+v, want unchanged inherited approval and metadata", got.Final) } if len(got.Requests) != 2 || !reflect.DeepEqual(got.Receipts, []string{"synthetic initial receipt"}) { t.Errorf("confirmation SDK error without TRANSACTION_RESULT requests/receipts=%v/%v, want one start, one confirmation and inherited receipt", got.Requests, got.Receipts) } }