Make instance UUIDs stable across restarts

[itssimon]

Summary by CodeRabbit

• New Features

  • Added a file-based distributed instance locking system to manage and persist instance identity across runs.

• Chores

  • Ignored local editor settings (VS Code) in repository configuration.

• Tests

  • Added comprehensive unit tests covering lock creation, reuse, slot handling, and recovery from stale or invalid lock data.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a new file-based InstanceLock class and tests, integrates it into ApitallyClient (replacing direct UUID generation), and updates .gitignore to ignore the VS Code folder.

Changes

Cohort / File(s)	Summary
Configuration \.gitignore	Adds .vscode/ ignore entry with a preceding comment and blank line for separation
Instance Lock Implementation src/main/java/io/apitally/common/InstanceLock.java	New public class implementing file-based locking with per-client/environment hash slots, UUID persistence, stale/invalid lock handling, and resource close API (getInstanceUuid(), create(...), close())
ApitallyClient Integration src/main/java/io/apitally/common/ApitallyClient.java	Replaces UUID instanceUuid with InstanceLock instanceLock; obtains UUID via instanceLock.getInstanceUuid() when building payloads and calls instanceLock.close() on shutdown; removes unused UUID import
Tests src/test/java/io/apitally/common/InstanceLockTest.java	New JUnit tests validating UUID creation/reuse, environment isolation, multi-slot behavior, and recovery from stale/invalid lock files

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Make instance UUIDs stable across restarts' directly describes the main objective of this pull request, which is to replace random UUID generation with a file-based distributed locking mechanism that persists instance UUIDs across application restarts.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch simon/dev-43-make-instance-uuids-stable

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/main/java/io/apitally/common/InstanceLock.java`:
- Around line 64-85: The FileLock obtained by channel.tryLock() must be retained
and released explicitly: modify the InstanceLock class to add a private final
FileLock lock field, update the constructor(s) to accept and store the FileLock
(in addition to the existing FileChannel parameter), and change the factory code
that currently calls new InstanceLock(uuid, channel) to pass the acquired
FileLock (the local variable from tryLock) so the lock isn't only a transient
local. Implement or update InstanceLock.close() to first call lock.release()
(guarded for null/closed), then close the channel, ensuring deterministic,
platform-independent lock release instead of relying on GC/close behavior.

In `@src/test/java/io/apitally/common/InstanceLockTest.java`:
- Around line 32-43: The tearDown method uses Files.walk(tempDir) but never
closes the returned Stream<Path>, leaving directory handles open; change the
cleanup to use a try-with-resources around Stream<Path> (e.g., try (Stream<Path>
stream = Files.walk(tempDir)) {
stream.sorted(Comparator.reverseOrder()).forEach(...); }) so the stream is
closed automatically, keeping the existing deletion logic and exception handling
inside the forEach; reference the tearDown method, tempDir variable, and
Files.walk call when making this change.

🧹 Nitpick comments (1)

src/main/java/io/apitally/common/InstanceLock.java (1)

120-123: Consider a longer hash prefix to lower collision risk.
A 4‑byte prefix (32‑bit) can collide when multiple clientId/env pairs exist on the same host, leading to shared lock files/UUIDs. Expanding to 8+ bytes keeps filenames short but meaningfully reduces risk.

♻️ Suggested tweak

-        return HexFormat.of().formatHex(hash, 0, 4);
+        return HexFormat.of().formatHex(hash, 0, 8);

[codecov]

Codecov Report

❌ Patch coverage is 77.41935% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.07%. Comparing base (270afaa) to head (5b834b6).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/main/java/io/apitally/common/InstanceLock.java	75.86%	9 Missing and 5 partials ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main      #51      +/-   ##
============================================
- Coverage     77.37%   77.07%   -0.31%     
- Complexity      314      326      +12     
============================================
  Files            31       32       +1     
  Lines          1061     1121      +60     
  Branches        134      140       +6     
============================================
+ Hits            821      864      +43     
- Misses          163      175      +12     
- Partials         77       82       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.