Files
hardlink/README.md
T
2026-10-23 14:33:24 +01:00

270 lines
10 KiB
Markdown

# 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 `:<port>` 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
<LayoutOptions>
<LogoPath>C:/Logo/logo.png</LogoPath>
<TopMostText>Welcome to the hotel</TopMostText>
<BeforeRoomNumberText>Your room number is</BeforeRoomNumberText>
<BeforeDirectionsText></BeforeDirectionsText>
<HotelSpecificDetails>Hotel information</HotelSpecificDetails>
<CheckOutTimeText>Check Out Time</CheckOutTimeText>
<RoomMapFolderPath>C:/Logo/Roommaps</RoomMapFolderPath>
</LayoutOptions>
```
## 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
<roomdetails>
<customername>John Doe</customername>
<checkoutdatetime>24/10/2026 11:00 am</checkoutdatetime>
<roomno>103</roomno>
<roommap>map.png</roommap>
<roomdirections>Follow the corridor...</roomdirections>
</roomdetails>
```
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 `<logdir>/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 <version>`
from the `development` branch. It builds Hardlink and the release task, packages
the existing `ChipDNAClient/` directory into `hardlink_windows_<version>.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 '<target-minion>' state.apply hardlink
```