Files
hardlink/docs/operations.md

8.1 KiB

Operations

Project overview | Configuration | Payment API

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.

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:

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.

See configuration for local settings, the CMS payment field mapping and the room-ticket layout.

Door cards

POST /issuedoorcard accepts Content-Type: application/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. Success returns:

{"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 complete K720 issuance contract covers worker ownership, preparation, uncertain-handoff recovery, delivery clearance, cancellation and idle maintenance. It includes the single LockSequence, shared three-shake budget, log-only delivery errors and best-effort next-card prestaging rules. Concurrent recovery with the actual dispenser and lock server still requires controlled physical validation.

Room tickets

POST /printroomticket accepts Content-Type: application/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:

{"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.

Additional endpoints

Endpoint Purpose
GET /dispenserstatus Cached stock/status in a code/message JSON response
POST /testissuedoorcard Operational diagnostic, available regardless of TestMode: encode and retain the card inside the dispenser; no guest delivery
GET /ping-pdq Read ChipDNA terminal status
POST /logerror Receive ChipDNA error notifications

/testissuedoorcard is an operational hardware diagnostic available regardless of TestMode. It prepares and encodes a card without FC0 guest delivery; the card remains inside the dispenser for reuse. Its registration and hardware sequence are separate from normal issuance and are not restricted to development kiosks.

Native-only endpoint cleanup

The modern /api/payment/sale, /api/payment/preauth, /issuedoorcard and /printroomticket endpoints serve native Fyne HTTP clients. They no longer emit browser CORS headers or accept OPTIONS preflight requests; non-POST methods receive the existing method-rejection format. Successful POST payloads, responses, payment execution and hardware sequences are unchanged. Keycard requests need only roomField, checkinTime, checkoutTime and followStr.

/dispenserstatus and /ping-pdq are GET diagnostics (other methods return 405 with Allow: GET). The ChipDNA sidecar's asynchronous POST /logerror, error notifications and availability debounce remain operational. Background dispenser polling is unchanged.

/testissuedoorcard is unconditionally registered on production kiosks and retains its encoded card for reuse. No TestMode gate or automatic ejection has been added. The deprecated XML /takepayment and /takepreauth handlers and their required response/redirect helpers remain for their explicitly retained contract. Do not remove the active sidecar or printer/lock-server protocols as browser legacy.

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:

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'
$env:TEMP = $env:GOTMPDIR
$env:TMP = $env:GOTMPDIR

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.

The existing run_tests.sh is not an offline verification entry point: it runs go mod tidy and unfiltered full tests, including the live-email test. Use the explicit commands above instead. Do not launch the service against hotel configuration as part of offline 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:

salt '<target-minion>' state.apply hardlink

Coordinated application releases

Deploy compatible ChipDNAClientCLI, Hardlink and native Fyne versions together. The module path is gitea.futuresens.co.uk/futuresens/hardlink/v2; internal and public package imports include /v2. The application buildVersion does not publish a module tag automatically.

The owner must commit and publish the intended v2 release before the Fyne applications pin its actual tag with go get and regenerate sums with go mod tidy. Until publication, their zero pseudo-version marker is local-only and resolves through ignored alternate modfiles replacing the /v2 module with the sibling checkout. Do not commit that replacement or invent remote checksums. The existing Fyne/CMS/translate dependency replacements are independent.

Hardlink itself builds and tests from this checkout using its tracked module files. Release history is recorded in releases.