Support sharing definitions between repos with different languages/package managers

[chrissimon-au]

Background

#36 introduced support for sharing definitions between repositories, but it relies on leveraging an existing sharing mechanism between those repositories - package distribution (e.g. go get, npm, nuget, etc.).

There are also use cases where there are no existing packages shared between repositories, and yet they both relate to the same bounded context. A typical example is a split between a front-end (e.g. in JavaScript/TypeScript) and a backend (e.g. in go, NodeJs, Ruby, .NET, JVM, etc.).

There is a case to be made that splitting such repos is an antipattern from the perspective of keeping all code associated with a bounded context in a more cohesive manner (e.g. a single repo), since functional changes are likely to affect all code that is a manifestation of that bounded context. However, current CI/CD tooling is far more attuned to aligning repositories with deployable components rather than logical components, so for the time being, this is definitely a scenario that Contextive needs to handle.

Options:

Considered approaches for sharing with pros & cons:

Raw URL from hosted source control

Common hosted source control platforms (e.g. github, bitbucket, gitlab) offer a raw URL to retrieve a file from a repo.

• Pros:
  • Simple mechanism to retrieve the file
• Cons:
  • Have to poll the URL to retrieve updates
  • Have to authenticate the URL, which likely means storing auth credentials (added security burden) or prompting for credentials (user friction)
  • Only works if the repo has such a RAW url

Clone repo into tmp folder

Could clone a nominated repo into it's own tmp folder and identify the file in that repo

• Pros:
  • Able to retrieve the file, even if no RAW url available
• Cons:
  • Have to poll the repo (fetch/update) to retrieve updates
  • Have to authenticate to clone. Might work seamlessly if the user has stored credentials (e.g. ssh key), but would be painful if not
  • Have to clone the whole repo - no way to get a single file (e.g. github explicitly blocks the git archive mechanism)

Self-published/hosted

Much like how many teams publish a swagger/json file alongside their API, a contextive definitions file could be included in a build process as an artifact, and thus made available at a URL in a preproduction (or even production) environment

• Pros:
  • Potential to access the file at a simple URL with no authentication
• Cons:
  • More effort for teams to publish the definitions file
  • Teams may not like the file being publicly available (may have auth, vpn, or source IP restrictions)

[lukespice]

Thanks for this, they are interesting options and I agree with the pros and cons assessments.

I really like the idea of self published or hosted like a swagger file as it could be a way to share the content with stake holders / domain experts who don't have access to the source code repository. Although I definitely agree with both of those cons, especially that there may be sensible objections to publicly exposing the details of your core domains.

Raw URL or cloning the repo both seem like sensible options and seem fairly equivalent usability. I would prefer whichever has the least friction. My current workplace at least all use SSH keys for Bitbucket connectivity as this is required for private Go packages so that shouldn't be painful for us.

[bluecitylights]

I am doing this self published for my integration events. The page describes both the external events the service subscribes to as well as the outgoing events. Next to our swagger.

[chrissimon-au]

Thanks for the info @bluecitylights - can you share a few more details on how/where you are publishing the files? And are you pulling them down into other repositories so contextive can work in those repositories?

Would you like contextive to offer more native/built in support for that pattern, or is it leveraging other things you're doing outside contextive (in which case it might make sense for contextive to be ignorant/agnostic as to how you're doing it...)