Skip to content

feat: add Formulus–Synkronus version handshake (major-version check and x-formulus-version header)#358

Merged
najuna-brian merged 11 commits intodevfrom
handshake
Mar 1, 2026
Merged

feat: add Formulus–Synkronus version handshake (major-version check and x-formulus-version header)#358
najuna-brian merged 11 commits intodevfrom
handshake

Conversation

@Ndacyayisenga-droid
Copy link
Contributor

@Ndacyayisenga-droid Ndacyayisenga-droid commented Feb 27, 2026

Description

This PR implements a version handshake mechanism between the Formulus React Native app and the Synkronus Go backend server. Every request from Formulus now carries its version, and Synkronus validates compatibility before processing anything. Incompatible versions are rejected immediately with a clear, user-friendly error.

Breaking Change

This PR introduces a breaking change by design. Any client not sending the x-formulus-version header receives HTTP 426 immediately. This is intentional, it establishes the version protocol from day one of the first release. Old Formulus builds without this header will be rejected.


How It Works

Every Formulus request includes a version header:

x-formulus-version: 1.0.0

Synkronus middleware intercepts every request and validates it:

Incoming request
      ↓
Header missing?          → 426 Upgrade Required
Header unparseable?      → 426 Upgrade Required
Server version dev/bad?  → 426 Upgrade Required
Major versions differ?   → 426 Upgrade Required
Major versions match?    → ✅ Request proceeds

Every response (success or error) includes:

X-Synkronus-Version: 1.0.0

This lets the client display exactly which server version it's talking to in error messages.

Version Compatibility Rules

Formulus Synkronus Compatible?
1.0.0 1.0.0 ✅ Yes
1.3.2 1.5.0 ✅ Yes — same major
2.0.0 1.0.0 ❌ No — major differs
1.0.0 2.0.0 ❌ No — major differs

Known Limitation is iOS Version Sync

syncNativeVersion.js currently only syncs to Android's build.gradle. iOS version fields in project.pbxproj are not updated automatically. If building for iOS, manually ensure MARKETING_VERSION in Xcode matches package.json. iOS automation is tracked as a future enhancement.

@Ndacyayisenga-droid Ndacyayisenga-droid changed the title Add Formulus–Synkronus version handshake (major-version check and x-f… feat: add Formulus–Synkronus version handshake (major-version check and x-formulus-version header) Feb 27, 2026
@najuna-brian najuna-brian requested review from najuna-brian and removed request for najuna-brian February 27, 2026 02:27
@najuna-brian najuna-brian marked this pull request as ready for review February 27, 2026 14:09
@najuna-brian najuna-brian requested a review from r0ssing February 27, 2026 14:10
r0ssing
r0ssing previously approved these changes Mar 1, 2026
Copy link
Contributor

@r0ssing r0ssing left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good!!

@najuna-brian najuna-brian merged commit 9990087 into dev Mar 1, 2026
11 checks passed
@najuna-brian najuna-brian deleted the handshake branch March 1, 2026 21:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants