# Hardlink Hardlink is the Windows hotel-kiosk service for K720 card dispensing, door-key encoding, room-ticket and payment-receipt printing, and terminal payments. It supports Assa Abloy, Omnitec, Salto, TLJ and dormakaba lock servers, and CreditCall (ChipDNA), Dojo and PayBridge payment providers. ## Build and run Run from the repository root on Windows with Go 1.23.2 or newer and access to the private Gitea modules. The entry point is `cmd/hardlink`, not the repository root. ```powershell go build -mod=readonly -o hardlink.exe ./cmd/hardlink go build -mod=readonly -o hardlink-preauth-release/preauth-release.exe ./hardlink-preauth-release ./hardlink.exe ``` `preauth-release.exe` is a separate task for releasing due CreditCall preauthorizations; the HTTP service does not run it automatically. Start Hardlink with the deployment directory as its working directory: ```text hardlink/ hardlink.exe config.yml TicketLayout.xml ChipDNAClient/ # Required for CreditCall ChipDnaClient.exe ... SDK dependencies and terminal configuration hardlink-preauth-release/ preauth-release.exe config.yml # Configuration for the separate release task logs/ ``` `config.yml` and the ChipDNA executable path are relative to the working directory. `TicketLayout.xml` is loaded beside the Hardlink executable. Configure the release task's working directory to contain its own `config.yml`. The HTTP server binds to `:` on all interfaces; the default port is `9091`. ## Configuration Example `config.yml` for card issuance and printing: ```yaml port: 9091 lockType: "assaabloy" lockservUrl: "http://192.168.4.109:4000" encoderAddr: "1" dispensPort: "COM9" dispensAddr: "15" printerName: "EPSON TM-T82II Receipt" logdir: "./logs" isPayment: false ``` - `lockType` is required: `assaabloy`, `omnitec`, `salto`, `tlj` or `kaba`. - `cert` supplies the certificate value used by TLJ's GuestCard API. - `dispensAddr` is the two-character serial device address. - `printerName` must match an installed Windows printer. - Payment setup additionally uses `isPayment`, `hotel`, `kiosk`, `cmsurl` and, when CMS does not select a provider, `paymentProvider` (`creditcall`, `dojo` or `paybridge`). Provider-specific terminal settings are read from CMS. - SQL configuration uses `dbport`, `dbname`, `dbuser` and `dbpassword`; configure these for monetary CreditCall PREAUTH persistence and the release task. - `senderroremails` contains recipients for operational error emails. - `timeoutSeconds` defaults to `300` for the generic payment handler. CreditCall retains its independent 300-second start/confirmation call bounds. Example `TicketLayout.xml`: ```xml C:/Logo/logo.png Welcome to the hotel Your room number is Hotel information Check Out Time C:/Logo/Roommaps ``` ## Door cards and K720 recovery `POST /issuedoorcard` accepts `Content-Type: application/json`: ```json { "roomField": "101", "checkinTime": "2026-10-23 15:00:00 +0100", "checkoutTime": "2026-10-24 11:00:00 +0100", "followStr": "0" } ``` Times use `2006-01-02 15:04:05 -0700`. A successful response is: ```json {"code":200,"message":"Card issued successfully"} ``` Errors use the same `code`/`message` JSON structure with an HTTP error status. Exact physical empty (`0x38`) during preparation returns `503`; preparation exhaustion and encoding errors return `502`. The serial worker exclusively owns AP, RS, FC7 and FC0 communication. Preparation uses fresh AP observations, a 32-second preparation budget, one-second polling, and at most three RS/shake recoveries. A valid encoder position permits encoding immediately. Uncertain or unusable observations after FC7 share a four-second window before an uncertain handoff may permit one encoding attempt. Only an uncertain handoff enables recovery concurrently with the single `LockSequence`. It carries forward the shakes already used and runs the remaining `RS -> 2-second settle -> AP -> FC7 -> AP` recovery sequence. Encoder confirmation stops recovery, including before FC7 if the diagnostic AP confirms the card. Unusable diagnostic AP is logged; it does not create a new fatal encoding error. There is no second `LockSequence` or extra plain FC7 retry. When `LockSequence` returns, the handler cancels and joins recovery before one FC0 delivery attempt. Caller cancellation stops recovery; already-started encoding retains its original lock-server timeout and result. Recovery/FC0 errors do not replace that result. Successful encoding keeps the existing best-effort next-card prestage. Idle maintenance and passive status polling remain separate from the foreground issuance operation. See the [K720 dispenser contract](internal/dispenser/K720_DISPENSER_CONTRACT.md) for status classifications, clearance rules, recovery limits and cancellation. Concurrent recovery still requires validation with the physical K720 and lock server. ## Room tickets `POST /printroomticket` accepts `Content-Type: application/xml`: ```xml John Doe 24/10/2026 11:00 am 103 map.png Follow the corridor... ``` Success returns HTTP `200` with: ```json {"code":200,"message":"Print job sent successfully"} ``` The printer package loads the ticket layout, renders ESC/POS text and raster images, and sends the output to the configured Windows printer. ## Payments | Endpoint | Request | Purpose | | --- | --- | --- | | `POST /api/payment/sale` | JSON | SALE streaming for CreditCall, Dojo or PayBridge | | `POST /api/payment/preauth` | JSON | CreditCall PREAUTH/account-verification streaming | | `POST /takepayment` | `text/xml` | Legacy CreditCall SALE | | `POST /takepreauth` | `text/xml` | Legacy CreditCall PREAUTH/account verification | The streaming endpoints return `application/x-ndjson`: progress frames followed by a final result. CreditCall's structured final frame uses `result`; Dojo/PayBridge use their existing `response` frame. Progress is observational and never determines payment success or failure. SALE JSON example (integer minor units): ```json {"amount":1234,"confirmNo":"BOOKING-123","currency":"GBP"} ``` CreditCall monetary PREAUTH JSON example (string fields): ```json {"amount":"3100","transactionType":"Sale","checkoutDate":"2026-10-24 00:00:00 +0000"} ``` Zero-value account verification: ```json {"amount":"","transactionType":"AccountVerification","checkoutDate":""} ``` CreditCall SALE confirms approved starts; PREAUTH does not confirm. PREAUTH uses the provider-returned `TRANSACTION_TYPE` and `TOTAL_AMOUNT`. Approved returned `ACCOUNT VERIFICATION` needs no amount and is not persisted. Approved returned `SALE` schedules persistence using the returned amount; it never substitutes the request amount. SQL failures fall back to `preauth_spool.ndjson` in `logdir`. The current SQL release date is checkout plus 96 hours, using the existing local-midnight date conversion. After financial dispatch, a kiosk disconnect stops stream delivery without cancelling CreditCall result processing, SALE confirmation, receipts or PREAUTH persistence scheduling. Never restart a transaction or fall back to a legacy endpoint because streaming delivery failed. Deploy a matching ChipDNAClient build: Hardlink starts `./ChipDNAClient/ChipDnaClient.exe` and calls it on `127.0.0.1:18181`. That deployed EXE must include `TRANSACTION_TYPE` and optional `TOTAL_AMOUNT` in its streaming allowlist; an older build can support SALE while breaking PREAUTH classification. See [CreditCall streaming](CREDITCALL_STREAMING.md) for frame schemas, progress ownership and timeout details. The current SQL implementation in `internal/db/db.go` defines release scheduling. ## Additional endpoints | Endpoint | Purpose | | --- | --- | | `/dispenserstatus` | Cached stock/status in a `code`/`message` JSON response | | `POST /testissuedoorcard` | Diagnostic issuance path; not the normal delivery workflow | | `/ping-pdq` | Read ChipDNA terminal status | | `POST /logerror` | Receive ChipDNA error notifications | ## Logging JSON logs are written to `/hardlink.log`. Weekly rotation uses local Monday midnight and retains `hardlink.1.log` through `hardlink.13.log`. The separate release task writes `preauth-release.log` with the same rotation policy. K720 logs include uncertain handoff, raw AP status/classification, RS/FC7 attempts, remaining shake budget, recovery stop reason and encoding duration. PREAUTH logs include processor result/type, transaction reference, approval/persistence decision, missing fields, and SQL/spool outcomes without card or receipt payloads. ## Verification Use repository-local build and temporary caches from PowerShell: ```powershell New-Item -ItemType Directory -Force .cache/go-build, .cache/tmp | Out-Null $env:GOCACHE = Join-Path $PWD '.cache/go-build' $env:GOTMPDIR = Join-Path $PWD '.cache/tmp' go test -mod=readonly -count=1 ./internal/dispenser ./internal/handlers go test -mod=readonly -race -count=1 ./internal/dispenser ./internal/handlers go test -mod=readonly -count=1 -skip '^Test_SendMail$' ./... go vet -mod=readonly ./... go build -mod=readonly ./... git diff --check ``` `Test_SendMail` sends real email and is excluded from offline verification. Automated tests do not replace physical dispenser, encoder, terminal or printer validation. ## Deployment Production deployment uses Salt. Build the intended revision and deploy the versioned Windows package through the Salt repository and Hardlink pillar. Where installed, local release tooling is invoked as `bash ./winbuild.sh ` from the `development` branch. It builds Hardlink and the release task, packages the existing `ChipDNAClient/` directory into `hardlink_windows_.zip`, and copies it to `salt/hardlink/files`. It also checks out/pulls the Salt and pillar repositories and commits/pushes the package in Salt; it does not create a Git tag. Ensure `ChipDNAClient/` contains the intended build before packaging. Update `pillar/hardlink/init.sls` to select the package version, then apply the Hardlink state to the intended hosts: ```bash salt '' state.apply hardlink ```