# ForgeFlux [ForgeFlux](https://forgeflux.org/) aims to implement federation in [software forges](https://en.wikipedia.org/wiki/Forge_(software)), enabling a decentralized development environment. ## Why is this significant? Free software developers are asked to choose between freedom and having access to a large community while choosing a software forge.\ This has resulted in various forge spaces for projects being set up according to the comfort/preference of the developer community centered around the project. While this is great for the developer base which is invested in the project, the exposure that is provided to the project falls significantly short.\ The initial [forgefed](https://forgefed.peers.community/) was an attempt to bridge this gap, by introducing the concept of bridging the gap between forges.\ This approach required for the forge developers to actively participate in the development of the software. With ForgeFlux, we are trying to implement federation external to the forge, entirely using the forge’s API. Our approach involves implementing adapter-like software, called Interfaces, that interact with the forge’s API and speak a common protocol. ForgeFlux, consists of a terminology for the development and utilization of it\'s software, which result in terms such as `forges`, and `interfaces` being tossed around.\ It is recommended for a reader to go through the [ecosystem-architecture](https://github.com/forgeflux-org/spec/blob/master/rfc/1-ecosystem-architecture/1-ecosystem-architecture.md), if there is any confusion regarding the usage of particular words in this documentation. ## Features ### Forge Independence The services that Forge Flux seeks to provide aims to keep progression of a project, and the forge on separate terms, ensuring that a user\'s preference for a forge does not dictate their dedication towards the project. ## Getting Started ### How does it work? Interfaces are services that are run on the side of any user, and are used as connecting points of the bridge.\ These interfaces are responsible for communicating with each other, and interact in the form of messages for a server-server model, and a REST API model for the server-user model. Interfaces are geared towards performing various operations for the repository, which include but are not limited to, - Pull Requests - Issues - Comments - Notifications - Forking However, as the count for interfaces go up in magnitudes, it becomes increasingly hard to keep track of them.\ This is where Northstar comes to play, by implementing a lookup server that seeks to provide an indexed list of available forge interfaces. ForgeFlux is currently in the Active Development phase, and is being worked on towards the alpha-testing stage. ### What are the services present in ForgeFlux? 1. Northstar Repository : <https://github.com/forgeflux-org/northstar> OpenAPI : <https://northstar.forgeflux.org/docs/openapi/> ForgeFlux allows for multiple interfaces to be run against a single software forge.\ Also, the protocol is flexible enough to support multiple types of software forges(GitLab, GitHub, etc).\ The protocol\'s decentralised nature makes it impossible to create a constant record of which interfaces service forges. So we created a discovery service which stores records of interfaces and the forges they service.\ This is very similar to the way DNS works.\ In DNS, hostname is resolved to IP address. Here, software forge URL is resolved to URLs of [interfaces](https://github.com/forgeflux-org/interface) that service the queried forge. 2. Interface Repository : <https://github.com/forgeflux-org/interface> OpenAPI : <https://github.com/forgeflux-org/interface/tree/master/docs/openapi> Developing Free Software is about liberating users and giving them total control over how the programs they run should work.\ It\'s only fair that developers of such software enjoy the same levels of liberty. ForgeFlux is an attempt to enable federation for major software forges(GitLab, GitHub, Gitea, Source Hut, etc) entirely in API-space.\ We believe our API-space implementation will allow for more organic growth as it will not require any involvement from the forge developers. ### Technical Stack & Components 1. Northstar Northstar is a lookup service that allows for the ForgeFlux ecosystem to discover interfaces present for various forges.\ The technology that is utilized in the case of northstar, is as follows, Flask : Underlying backend for the development of the service.\ SQLite : Database for storage of the details of the various forges. 2. Interface Interface is a service that can be set up by any user with an account in the forge and an authentication token. (Example: Personal Access Token in GitHub)\ This service can be run on a local machine setting up an instance, which can be updated in Northstar. Proceeding forward, these interfaces can be located by the user in Northstar, through the `GET` request for forge interfaces. More of which is covered in the [OpenAPI specification](https://northstar.forgeflux.org/docs/openapi/).\ The technology that is utilized in the case of interface are as follows, Flask : Underlying backend for the development of the service. API Controllers : The methods developed are made to utilize existing APIs present for the forges. [Libgit](https://github.com/forgeflux-org/interface/tree/master/libgit) : A Rust library made for the git interface for the forgeflux instance. ### `Interface`: Developer Workflow As of right now, the developer workflow for Forge Flux\'s interface and northstar is based on the concept of [Test Driven Development](https://en.wikipedia.org/wiki/Test-driven_development).\ None of the functionality are immediately usable, and as such, would require you to develop tests for progress validation. 1. Set up the development environment The development environment for northstar and interface, both have a requirement for Python, and it\'s dependencies.\ These dependencies can be installed through a simple `pip install -r requirements.txt` command, however, there is a better alternative. The pre-requisites for installing the dependencies would be, [Python](https://wiki.python.org/moin/BeginnersGuide/Download) : For the interface. [Rust](https://www.rust-lang.org/learn/get-started) : For Libgit. [Virtualenv](https://virtualenv.pypa.io/en/latest/) : As a Makefile cannot create a virtual environment without a pre-existing module for it, we will need to install virtualenv before we run the setup commands. ForgeFlux makes things easier for a development or a CI to function through the use of a [Makefile](https://makefiletutorial.com/).\ So, installing dependencies for the development environment could be as easy as, ``` {.bash org-language`"sh"} pip install virtualenv virtualenv venv make env ``` Where `make env` serves the purpose of installing all the dependencies required for the project.\ The pythonic dependencies are installed via the default `pip` installer. The dependencies for the `libgit` library, are however installed by leveraging the features provided by the `maturin` package.\ Maturin runs cargo under the hood, compiling, packaging and installing `libgit` into `interface`\'s virtual environment. In order to run an interface, you could simply call the following command, ``` {.bash org-language`"sh"} make ``` However, this should only be done with a production ready model, and quite unfortunately, we\'re not there yet. 2. Project Structure The project structure for interface is segmented, and is provided as below, ``` . ├── config ├── docs │   └── openapi │   └── api ├── instance ├── interface │   ├── api │   │   └── v1 │   ├── db │   ├── forges │   │   ├── gitea │   └── runner ├── libgit │   ├── src ├── scripts ├── tests │   ├── api │   │   └── v1 │   ├── db │   ├── forges │   │   └── gitea │   └── runner ``` The `config/` directory is used as a medium to store the user's configuration for interface, and the project implements [Dynaconf](https://www.dynaconf.com/) to handle these configurations to be utilized in the project. The `docs/` directory is used to store all sorts of documentation for the project, and consists of the OpenAPI specification of the project as of right now. The `instance/` directory is where the initialized database is stored for the project, which assists in abstracting all the database related operations. The `interface/` is the Flask application, which consists of the source code components that make up the essence of the interface. `libgit` is the Rust library that we utilize and leverage to perform git interface related tasks. The `scripts/` directory consists of simple ease-of-life scripts that assist in coverage, spell checking, and clean up. `tests/` is a section dedicated to the mocks that we run against the code, and is how ForgeFlux continues to be developed. # Irrelevant notes Works by storing the state that they require.\ Look into actor system.\ Tell the actor and get them to mutate the data, owned by a single thread. The sum variable is contained within an object, the only way to interact with this object, is to send something using a queue.\ Every time you wish to add something, you just send it to the queue. Your computation will be executed when the actor gets to it.\ The biggest problem with concurrent programming, would be to make the same data available across threads.\ The actual data is tracked by a single thread alone.\ If you want something you ask for it. When you send a message,\ When you use locks, you restrict it to a machine.\ You create a logical processor.