July 09, 2021

Monolithic wireleap repository split, released under MIT

The wireleap monolithic git repository containing the Wireleap software suite has been split, mainly into component repositories with a few more repositories based on maintainability, interoperability, separation of concerns and the DRY principle.

Splitting a monolithic repository, especially for a decentralized and distributed system composed of multiple components needing to interoperate with each other poses several additional challenges above the usual. Hence, there is a valid a reason why projects such as kubernetes use a mono-repository.

None the less, after weighing the pros and cons, we’ve decided to make the split mainly due to the following rationale:

  • Incrementally release code publicly under an open source license, and perform development in the open on said code - as opposed to using a band-aid approach of maintaining both public and private repositories.

  • Perform component specific semantically versioned releases as opposed to the entire software suite requiring a version bump. Additionally, improve versioning as a whole by having separate software versions, and inter-component communication versions.

  • Improved access control, maintainability, separation of concerns, flexibility, and forced code uncoupling.

GitHub repositories

Some of the post-split repositories have been released under the MIT license. Others will follow when they are ready…

RepositoryCommentLicense
commoncommon go-packages which are used by 2+ componentsMIT
clientwireleap client (incl. tun and intercept)MIT
relaywireleap-relay componentMIT
contractwireleap-contract component
dirwireleap-dir component
authwireleap-auth component
ps-dummyexample dummy payment system
ps-stripeexample stripe payment system
localtestnetlocaltestnet and integration testing suite
gh-buildGitHub action for builds, unit-testing and releasesMIT

Versioning

In the mono-repository, all components shared the same semantic software release and protocol version. This actually worked quite well, was convenient, but not very optimal looking forward.

With the split and this release:

  • Each component has its own software version (depicted by the git tag).
  • Each component depends on a specific version of common, which is a collection of go-packages used by 2+ components.
  • Component to component communication will be versioned semantically, for example: client-relay, relay-relay, relay-contract, etc.

This is the last software version where all the latest component software versions are equal. From now on, the component software versions will be bumped individually as needed, along with the component-component communication interaction versions.

Automated builds, tests, and releases

A tricky part of the split was retaining the CI/CD flow with regards to integration testing.

The solution is best visualized in this sequence diagram showing the high-level flow and behind the scenes of the processes triggered when a Wireleap component repository receives a pull-request, a branch is merged into master, or a signed release git tag is pushed.

sequenceDiagram participant component participant gh_build participant gh_test participant staging participant localtestnet participant releases component->>+gh_build: trigger() gh_build->>+component: fetch() component-->>-gh_build: repo gh_build->>gh_build: unit_tests() gh_build->>gh_build: build() gh_build->>+staging: upload(build) deactivate staging gh_build->>+gh_test: trigger() gh_test->>+staging: download() staging-->>gh_test: components builds deactivate staging gh_test->>+localtestnet: fetch() localtestnet-->>-gh_test: repo gh_test->>gh_test: integration_tests() gh_test-->>-gh_build: response opt git_tag gh_build->>gh_build: build_release() gh_build->>+releases: upload(artifacts) + issue release releases-->>-gh_build: response end gh_build-->>-component: response

Releases have been moved to their relative GitHub repository utilizing the releases feature. Inline with this, the upgrade mechanisms (client, relay) have been updated accordingly.

Note: The automatically built binaries have been mirrored to /dist to enable inline upgrades of existing client / relay deployments.

Documentation and issue tracking

Each repository now has a README.md housing the specific components documentation. The old documentation will be removed or updated shortly.

Issues will now be tracked per repository using the GitHub issue tracker feature.

Upgrades

Note: When upgrading the wireleap client - if wireleap_tun is owned by root, it should be removed prior to performing an inline upgrade:

sudo rm $HOME/wireleap/wireleap_tun
wireleap upgrade

Changes

wireleap

  • Technical release after code refactoring (mono-repo split).
  • Depends on wireleap/common v0.1.0.
  • Upgrade URL endpoint updated to GitHub releases.
  • Required removal of wireleap_tun if root owned prior to upgrade.
  • Imported get.sh convenience script, updated for GitHub releases.
  • Added missing stop sub-command to help tun.

wireleap-relay

  • Technical release after code refactoring (mono-repo split).
  • Depends on wireleap/common v0.1.0.
  • Upgrade URL endpoint updated to GitHub releases.

wireleap-contract

  • Technical release after code refactoring (mono-repo split).
  • Depends on wireleap/common v0.1.0.

wireleap-auth

  • Technical release after code refactoring (mono-repo split).
  • Depends on wireleap/common v0.1.0.

wireleap-dir

  • Technical release after code refactoring (mono-repo split).
  • Depends on wireleap/common v0.1.0.

ps-dummy

  • Technical release after code refactoring (mono-repo split).
  • Depends on wireleap/common v0.1.0.

ps-stripe

  • Technical release after code refactoring (mono-repo split).
  • Depends on wireleap/common v0.1.0.
  • Updated templates for new download and documentation locations.

localtestnet

  • Technical release after code refactoring (mono-repo split).