a Pull Request manager

• Java 17
• Maven 3
• a GitHub access token with at least scopes "read:user" and "repo"

It's a standard Maven build.

mvnw package

As this is Spring Boot application the default configuration source hierarchy applies, see Documentation.

For local development it is advantageous to copy the file application-local.properties.template to a new file application-local.properties and then run the application with the active spring profile local, e.g. via -Dspring.profiles.active=local.

The web app runs on http://localhost:8080 by default.

Login with a GitHub username and the string value of a personal access token.

This page serves as the home page after login and lists all repositories the user has direct access to. This does not include all public GitHub repositories.

From here it is possible to navigate to the Pulls page by clicking on a repository.

This page displays all pull requests in a given repository. The list is paginated with an item size of 30.

If no repository was chosen (via Repos page) it is also possible to directly specify the repository via text input. The input format is owner/repository.

Clicking on a pull request navigates to the 'Pull Request Details' page.

This page lists further details about the chosen pull request.

If the given pull request is not closed it can be closed here.

If the given pull request is merge-able (as per the API), the user can request the merge here. The merge will use a predefined commit message and the last known head revision of the underlying branch to guard against merging unseen changes.

For any pull request it is possible to request the download of a zip archive containing the repository state at the head revision of the pull request. This action navigates to the Downloads page.

The Downloads page displays all current and past downloads requested.

A download can be in the following states:

• Running
• Finished
• Error

If a download is in the Finished state it can be retrieved via the Get Zip action.

If a download is not Running it can be deleted.

If a download gets requested (via the Pull Request Details page) that already exists, it is not executed again regardless of its state.

For the sake of simplicity and to not waste effort on unrelated problems, tech choices were made in favor of familiar options unless otherwise necessary.

Amongst others this means:

• Java instead of Kotlin
• Maven instead of Gradle
• Spring Boot instead of dagger2 / guice
• Template based frontend instead of JS-based SPA + API
• no reactive paradigms

Spring RestTemplate is out of the picture as it is practically deprecated in favor of WebClient. The latter won't be used as it only supports reactive interactions which are ruled out by DD.1.

The JVM 11 java.net.http client would be a pragmatic first choice but it doesn't provide all the necessary features like preemptive authentication.

In a bigger project integration of contract-based techniques like Feign and/or OpenAPI would be chosen to enhance maintainability.

Integration works against the GitHub Rest API to keep things simple.

One major disadvantage is that the Rest response bodies can get quite large and not all the info is needed. Usage of GraphQL would rectify this problem.

The GitHub API gives back complete URLs ones could use to navigate, e.g. from repo to pull requests. Due to how the application is structured, usage of those URLs from a given DTO to later calls would necessitate feeding back those URLs into request parameters. This could be problematic because we would still need to verify that the URLs are genuine and not malicious. So for the time being URLs will be constructed as stated in GitHub's API documentation.

It is a reoccurring question on how to handle errors in business logic. A number of different approaches are thinkable:

• Checked Exceptions
• Result Types
• Functional Either composition
• Runtime Exceptions

Java comes with Option but not with monoic Either type and constructing one would be too complex for this task.

At the same time custom generic result types sooner or later tend to mimic the usage pattern of classic exceptions (causes, message concatenation, etc.) . Their only advantage is the cheaper runtime cost due to not needing any stacktrace construction. Their disadvantage is the custom usage pattern where one usually has to invoke check methods like Result#isOk before using the payload.

Hence the design decision to use runtime exceptions here even when their usage is sometimes frowned upon. To alleviate the cost of stack trace construction we will use so called lite weight exceptions which don't carry stack traces. This is in no way a perfect solution and not a proposal in general, but it fits with the task.

The main interaction with the GitHub rest API happens via the dedicated class GitHubClient. This class and the surrounding DTOs / value types are responsible for that.

Of note would also be the accompanying test cases for the client class. I used WireMock to mimic the GitHub API responses, including custom headers and redirects.

The cache for the downloaded zip files is made out of two parts.

The in-memory portion can be found in the class DownloadService. Downloads and their current states are kept in a ConcurrentHashMap. The interaction methods are supposed to make sure all state transitions happen in a valid order.

The disk portion of the cache is facilitated via the class FileStore. This part is responsible with storing the zip files in the appropriate file structure and to retrieve them later on.

On application startup both parts work in tandem to re-establish past successful downloads.

Strings are hardcoded to US english for now. Both Spring and Thymeleaf would support I18N via resource bundles though.

Currently there are rudimentary Server Side Events to basically trigger a reload of the downloads page on status changes. Due to all kinds of edge cases regarding browser compatibility / settings this is not a super solid solution and more like an 'extra'.

The OAuth scopes of a GitHub access token are quite broad. Even though we take the scopes and turn them into Spring Security's authorities this is not enough to make fine granular decisions. At the moment repository permissions are checked via the collaborators permission endpoint.

The GitHub API supports response caching via ETags. OkHttp already comes with an optional cache that could make use of that.

Also the download cache could be rewritten to make use of Spring's cache abstraction, then it would be possible to switch out the cache in favor of something like EhCache if the need should arise.

We already know the token lifetime, if we detect that it is in the past we could force a logout. Best way to do this would probably be a servlet request filter or Spring interceptor, to apply it globally.