hangarmc / hangar

A plugin repository used for paper plugins

Hangar - Paper's Plugin Repository

This is the repository for Hangar, a plugin repository used for Paper, Velocity, and Waterfall plugins and similar software.

Hangar is loosely based off of Ore, created by the Sponge project, but rebuilt from the ground up using the Spring Boot Framework in Java for the backend and Nuxt (with UnoCSS) for the frontend. We would like to thank all Ore contributors. Without them, this project would never have been possible.

On top of our production instance at https://hangar.papermc.io/, we have a staging instance for testing purposes: https://hangar.papermc.dev/.

Contributing

The project consists of 3 main parts

• Frontend (Vue.js under Nuxt with UnoCSS)
• Backend (Spring Boot)
• Database (PostgreSQL)

Development Setup

Fork the project and pull it in your IDE.

Prerequisites

• Docker is required in order to run the PostgreSQL database and the dummy email server
• Java 17 or higher
• pnpm
• mvn
• git

Setting up

To get the project running locally, you need to follow a few steps:

1. Get the dummy database, storage and email server up and running. Move to the docker folder cd docker then run docker-compose -f dev.yml up -d (-d as an optional parameter to run the containers in the background). Alternatively, if you are using IntelliJ you can press the green arrow in the docker/dev.yml file.
2. Move to the backend directory: cd ../backend. In that directory, run mvn spring-boot:run, or if you're using IntelliJ, it is included in the run configurations.
3. Move to the frontend directory: cd ../frontend. In that directory, run pnpm install. This will install all the needed Node modules.
4. After the installation, run pnpm run dev in the frontend directory to initiate the build and launch. Changes you do to the frontend will be reloaded automatically.
5. After that, open http://localhost:3333, and if all went well, Hangar should be up and running.

Notes

• The Spring Boot configuration file that is used by this environment is located at backend/src/main/resources/application.yml.
• You can view the emails hangar sends on http://localhost:4436/
• On staging/prod Hangar uses object storage, if you want to test that you can install minio and change the storage type to object in the application.yml

Deployment

Deployment happens via a helm chart in the /chart folder. The Spring Boot configuration file used for deployment can be found at chart/templates/secret-hangar-backend.yaml (however it will be overridden with the actual values via helm).

Translations

Hangar uses Crowdin for translations. If you want to contribute to translations, create a Crowdin account at https://hangar.crowdin.com/hangar and simply add new translations or comment/vote on existing translations. You can learn more about navigating the Crowdin UI here: https://support.crowdin.com/online-editor/.

Getting translations locally (mostly for developers, requires Crowdin CLI, ran in root folder):

crowdin pull -b master -T <PAT>

You might want to set the env var TRANSLATION_MODE to true in order to get warnings about untranslated strings.

Contributing

Most of our current and future plans can be found in the Hangar Roadmap Project. Your best bet is joining the #development channel on the Hangar Discord to start discussing potential contributions and ideas. With Hangar being such a massive project, any contributions are welcome!

Updating the frontend dependencies can be done best by running npx npm-check -u and going through the changelogs. Note that package.json might contain hints to which dependencies are broken.

Tracing

If you want to have traces available locally, you can run zipkin via the docker-compose file zipkin.yml in the docker folder like this:

cd docker
docker-compose -f zipkin.yml up -d

Then just enable it in the application.yml under management.tracing. You also need to comment in the dependency in the pom.xml

License

Hangar is licensed under the permissive MIT License.

A large part of the backend is based on Ore, also licensed under MIT:

Copyright (c) SpongePowered <https://www.spongepowered.org>
Copyright (c) contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

hangar's Issues

Convert enums to frontend-modifyable db-backed lists

These enums should be converted into db tables that can be modified by an admin on the frontend.

• Category
• Color
• FlagReason
• Platform
• Role
• TagColor

this means it was decided NOT to convert from an enum.

• Platform (this isn't gonna change, like almost ever)
• Role (neither is this, and would probably take backend modifying anyways to implement the new role)

Standardized Maven/Gradle dependency view

If a project in on a repo, there should be a standard button to view/copy the dependency info for maven or gradle.

v1 api routes

v1 is the internal api used only by the frontend for dynamic content.

• POST /api/sync_sso
• POST /api/v1/projects/:pluginId/keys/new
• POST /api/v1/projects/:pluginId/keys/revoke
• GET /api/projects/:pluginId/versions/recommended/download
• GET /api/projects/:pluginId/versions/:name/download
• GET /api/v1/projects/:pluginId/versions/recommended/download
• GET /api/v1/projects/:pluginId/versions/:name/download
• GET /api/v1/projects
• GET /api/v1/projects/:pluginId
• GET /api/v1/projects/:pluginId/versions
• GET /api/v1/projects/:pluginId/versions/:name
• POST /api/v1/projects/:pluginId/versions/:name
• GET /api/v1/projects/:pluginId/pages
• GET /api/v1/users
• GET /api/v1/users/:user
• GET /api/v1/projects/:plugin/tags/:versionName
• GET /api/v1/tags/:tagId
• GET /api

Improvements/changes to file storage

Improve file blob storage (IchBinJoe wanted to take a shot at working out a concept) and otherwise add file size limits and a limit of builds in a specific time window for normal users (?)

dark theme / @media (prefers-color-scheme: dark) {

prolly wanna finish vue migration first I guess, also compare to PaperMC/papermc.io#50

Add HangarException exception resolver to automatically show errors on configured page

Instead of catching errors that should show up as alerts, we should add a custom exception resolver to automatically add the alert information to what is passed to freemarker. That was we dont have to go to each route and add the errors to the MaV manually. This should be possible.

Suggest(Feat): Github Releases integration.

Allow resources to be auto updated using github releases, and copy version + description from the release.

This would need some limitations (1 file releases only etc)

BBCode->MD converter for Spigot/DBO users

Make the jump to Hangar ever so slightly nicer by adding a button/field on project creation to import a ReadMe's contents, or to convert a Spigot resource page's description from BBCode to Markdown.

• A tab for the actual converter with plain text output
• A tab to preview the rendered markdown output
• A tab telling people how to get the BBCode from their Spigot project

Handle API errors differently

Currently, a 404 in an api method returns the html error page. It should return its own json error with a consistent error format.

Migrate JQuery to Axios/ES6+Babel

Migrate JQuery to Axios/ES6+Babel

Is this planned?

global annoucements

Should create a system for sending global announcements. There is already a bit of one with the Prompt system, but its limited at the moment. It uses an enum that only has one object, one to tell users to change their avatars when they first log in. This could be expanded to include custom ones that uses with a specific permission can create and send out.

MiniDigger suggested using the staging notification system and making that configurable, so there are a few options for this.

Add option to hide project/org membership

Sometimes you might just not want people to know (but always visible to staff). Should hide membership on projectpages (except for the primary owner in non-org projects) and org membership on the user- and orgpage.

Dropdown isn't working

Drop-down in left upper corner doesn't work on mobile, it refreshes page. Arrow icon is part of clickable link.

Translations

Shove everything into one format, then into a website like maybe POEditor, then export for both frontend and backend formats (maybe automate via maven the conversion of formats?)

Github

Extend #136 and #39
To add:

• An option to automatically pull description from readme when updated
• Prebuilt github action with Webhook implementation or however else you might implement an automatic deploy to dev channel
• Automatically sync releases, and move over more info than may not be possible in webhooks like description, file, channel (pre or main)
• Github Packages (and maybe jitpack?) links and auto updating widget to display latest version and pom/gradlefile copy paste info to add to repo.
• Issue/PR Count?
• Last Commit date?

More?

Github Action for creating Hangar releases

Describe this feature briefly

Hangar should support webhooks from GitHub for releases, such that when I release 1 place, it copies the description and links to the GH release/file on Hangar.

Alternatives considered

A self-hostable program to handle this for us, i.e. one that simply uses webhooks + Hangar API to release automatically. This could also be community provided.

migrate to bootstrap v4

Should update to bootstrap v4 (and eventually 5).

There aren't many breaking changes in v5 so it shouldn't be an issue if we upgrade to v4 before v5 is released.
migration guide
v5 blog post

Add Ownership Transfer

Ownership transfers for Projects/Organizations
Organization Owner and Project Owners should be able to transfer ownership to another user.

Proper multi-platform support

• Auto detect Paper/Waterfall/Velocity/... platforms as good as it gets and check those on project creation (as already done), but let the user check those manually as well (for example with the ambiguous plugin.yml / plugins working on multiple platforms w ambiguity) - one project has to be viewable/findable in multiple platform categories.
• Make sure the project (not only version) page clearly shows what platforms the project works on.
• The initial plan was for discussion to be sent to the Paper forum's plugin category, embedded in Hangar - this won't work for any other generic platform / would be limiting - what to do? (。_。)
• Dependencies should be listed under their platform (= have slightly separated sublists for dependencies).

Remove plugin id

Remove the plugin id from the creation page and its API usages, since (author and) slug already are the proper, case-insensitive identification used everywhere except for the API, and will only cause confusion for both people uploading plugins and people using the API.

Channel creation dialog broken

On the version creation screen, the channel creation is borked.

Route permissions

Each route needs to be checked to make sure only users with the proper permissions will be able to access it.

UserActionLog for project icons (store additional info)

Currently, the user action log for projects changing their icons, only lets admins know that the icon was not changed, there are TODOs in the methods for uploading new icons (POST /{author}/{slug}/icon) and resetting a project icons (POST /{author}/{slug}/icon/reset) to include additional info (a newState and oldState) in the logs. Not 100% sure what should go there, I thought maybe uploading the old images to somewhere else and putting the url in there. Or maybe storing an encoding of the image, but that could be big.

html template thru webpack -> file name hashes for assets/js/css

Add safety checks in controller methods

Add null and safety checks for user/version/org/... getting to either return a default "not found" 404, or a specific redirect with an informative alert whenever it may seem more fitting.

Create copy download URL button

Instead of having the copy url button in a drop down menu, put it next to the download button with the usual copy to clipboard icon.

db migrations

Add a system to handle database changes

Figure out the discussion page

Options basically are:

• Store discussion content on our own Apparently there is people actually liking Discourse and not having any interaction features
• Use the same kind of Discourse integration to the Paper forums that SpongeOre uses for its own forums

--

• With the first option, we might as well make individual messages look nicer (and not as bare-boned/soulless as Discourse)
• Reactions should be possible, but only with a selected few emojis (but a couple more than GH for example)
• Have a simple reply button, adding a short view of the message that is replied to in the text field

Convert to Vue components

An ongoing list of bits and pieces that should be converted to Vue components.

• project creation
• project settings
• org creation
• member list (project/organization)
• version creation
• user search bar (for better name suggestion)
• channel creation (probably?)
• api key creation (probably?)
• stats page
• user admin page
• version review log
• version approvals

Project/Version page diffs

Project owners, or well anyone who can edit pages/version pages on a project should have access to an edit history for that page. Currently that info is visible in the user action log, but that is only for Moderators/Admins. Along with this would come page rollbacks. This shouldn't be a big issue since that information is already stored in the logs table.

Fix and expand dependency sidebar

With plugin ids being removed (#141), project dependencies need to be updated as well, also with multi-platform support in mind.
This could mean:

• Searching a dependency on Hangar by slug and linking it by default if a match is found
• Being able to manually unlink a dep and set links yourself in project settings (possibly to other websites)
• Having dependencies per platform - in settings they have to be separated, and they have to be slightly separated in the project sidebar with the platform name as their header/split

Caching

Add caching annotations on the required service methods.

Can probably look at ore to see what exactly they cached.

Freemarker templates to port

Templates to port

• createOrganization
• swagger

Projects

• admin\flags
• admin\notes
• channels\helper\modalManage
• channels\helper\popoverColorPicker
• channels\list
• helper\alertFile
• helper\btnHide
• helper\createSteps
• helper\inputSettings
• helper\modalDownload
• pages\modalPageCreate
• pages\view
• versions\create
• versions\list
• versions\log
• versions\unsafeDownload
• versions\view
• create
• discuss
• settings
• tag
• userGrid
• view

Users

• admin\activity
• admin\flags
• admin\health
• admin\log
• admin\queue
• admin\reviews
• admin\stats
• admin\userAdmin
• admin\visibility
• invite\form
• invite\roleSelect
• invite\userSearch
• apiKeys
• authors
• memberList
• notifications
• projects
• staff
• view

Utils

• alert
• csrf
• editor
• email
• modal
• prompt
• userAvatar

Add informative cooldowns to project/version creation and member inviting

To prevent shit like this

Project/org creation, version uploading, and member invitations should get a certain limit with error tooltips instead of ratelimit's error pages. Version uploading could also use an informative banner before you hit a limit, reminding users of resource guidelines

Project pinning for profile page

Now implemented on the backend, just needs a frontend display with a way to add, remove, and sort them.

move frontend stuff from resource to frontend folder, make it actually use webpack and shit

also use babel to make it actually nice

User role dropdown for proj/org should default to current role when clicked

When an admin, or someone with perms goes to change a user's position in an organization or project, the dropdown to select the role should default to the users current role, rather than just the top one in the list.

Finish Auth (pre-Runway)

Yeah, so things that have to happen here...

• test /api/sync_sso with HangarAuth
• finish organization creation (remove manually insertion of org user into user tables on hangar's end)
• Runway??

v2 api routes

v2 is the external public api

• POST /authenticate
• POST /authenticate/user
• DELETE /sessions/current
• POST /keys
• DELETE /keys
• GET /permissions
• GET /permissions/hasAll
• GET /permissions/hasAny
• GET /projects
• GET /projects/:pluginId
• GET /projects/:pluginId/members
• GET /projects/:pluginId/stats
• GET /projects/:pluginId/versions
• GET /projects/:pluginId/versions/:name
• GET /projects/:pluginId/versions/:version/stats
• POST /projects/:pluginId/versions
• GET /users/:user
• GET /users/:user/starred
• GET /users/:user/watching

Webpack Code Splitting -> Remove Chunk Vendors

remove vendor chunk, make everything depend on main chunk, stuff like chart.js should only be used in its own file

http://127.0.0.1:8888/ to debug

see configureWebpack.optimization.splitChunks.cacheGroups for info

Add supported version selector

Since the full range of supported versions can't be detected automatically and so that people don't have to put it into their docs manually, add checkboxes for version support in project settings and have a small display on the project's sidebar

RouteHelper route format

In order to remove the need to get the route url for a view by a string, the routes should be some constant.

Unsure of what the final form should look like

routeHelper.getRouteUrl(Routes.ROUTE_NAME, pathArgs..., queryArgs...)

or

Routes.ROUTE_NAME.path(pathArgs...).query(queryArgs...)

add additional "Save Changes" button to the top of project settings

Simply add an additional "Save Changes" button to the top of the settings page for projects. Bit of an small annoyance to scroll all the way to the bottom when you just changed something small at the top.

Send emails in more events

Setup the email service and send emails to the user when needed.

Only spot I could remember off the top of my head. Edit or comment with others

• Account locked
• Ownership transfer request received/member invitation?
• Project/version deleted or set to private by staff (due to report)

more action logs

The infrastructure exists to support logging organization actions, yet there are no logged actions for organizations.

Probably should add a few for:

• avatar changed (not technically possible because that is handled by hangarauth)
• members added/roles added
• members removed
• member roles updated

EDIT: expanding this to other loggable stuff

User

• user lock/unlock
• api key creation/deletion

Project page

• page creation/deletion

or something along those lines. Edit/comment with more loggable actions.

Download/view stats

I think the download, individual download, views, and individual view stats all need to be implemented

• individual version downloads

• individual project views

• background task

This issue should also probably cover that background task that I think is supposed to exist to auto update those other two databases.

Support linking external download site per version

Support external download link when creating a new version instead of uploading a jar/zip file.

Mainly for projects that would require multiple jar uploads with the same version strings (plugins that support multiple platforms).

Frontend routes

• GET /assets/*file
• GET /favicon.ico

Admin

• GET /admin/user/:user
• POST /admin/user/:user/update
• GET /admin/approval/versions
• GET /admin/approval/projects
• GET /admin/flags
• GET /admin/flags/:id/resolve/:resolved
• GET /admin/health
• GET /admin/activities/:user
• GET /admin/stats
• GET /admin/log
• GET /statusz

Application

• GET /
• GET /linkout
• GET /signup
• GET /login
• GET /logout
• POST /verify
• GET /global-sitemap.xml
• GET /sitemap.xml
• GET /robots.txt

Projects

• GET /new
• POST /new
• POST /invite/:id/:status
• POST /invite/:id/:status/:behalf
• POST /pages/preview

Organizations

• GET /organizations/new
• POST /organizations/new
• POST /organizations/invite/:id/:status
• GET /organizations/:organization/settings/avatar
• POST /organizations/:organization/settings/members
• POST /organizations/:organization/settings/members/remove

Users

• GET /authors
• GET /staff
• GET /notifications
• POST /notifications/read/:id
• POST /prompts/read/:id
• GET /:user
• GET /:user/sitemap.xml
• POST /:user/settings/tagline
• POST /:user/settings/lock/:locked
• GET /:user/settings/apiKeys

End Users

• GET /:author/:slug
• GET /:author/:slug/stars
• POST /:author/:slug/stars/toggle
• POST /:author/:slug/flag
• POST /:author/:slug/visible/:visibility
• GET /:author/:slug/watchers
• POST /:author/:slug/watchers/:watching
• GET /:author/:slug/discuss
• POST /:author/:slug/discuss/reply
• GET /:author/:slug/manage
• GET /:author/:slug/manage/sendforapproval
• POST /:author/:slug/manage/save
• POST /:author/:slug/manage/rename
• POST /:author/:slug/manage/hardDelete
• POST /:author/:slug/manage/delete
• POST /:author/:slug/manage/members/remove
• GET /:author/:slug/versionLog
• GET /:author/:slug/flags
• GET /:author/:slug/notes
• POST /:author/:slug/notes/addmessage
• GET /:author/:slug/icon
• POST /:author/:slug/icon
• POST /:author/:slug/icon/reset
• GET /:author/:slug/icon/pending

Pages

• GET /:author/:slug/pages/:page/edit
• POST /:author/:slug/pages/:page/edit
• POST /:author/:slug/pages/:page/delete
• GET /:author/:slug/pages/:page
• GET /:author/:slug/pages/:page/:subpage/edit
• POST /:author/:slug/pages/:page/:subpage/edit
• POST /:author/:slug/pages/:page/:subpage/delete
• GET /:author/:slug/pages/:page/:subpage

Channels

• GET /:author/:slug/channels
• POST /:author/:slug/channels
• POST /:author/:slug/channels/:channel
• POST /:author/:slug/channels/:channel/delete

Versions

• GET /:author/:slug/versions
• POST /:author/:slug/versions/:version/approve
• POST /:author/:slug/versions/:version/approvePartial
• POST /:author/:slug/versions/:version/hardDelete
• POST /:author/:slug/versions/:version/restore
• POST /:author/:slug/versions/:version/delete
• GET /:author/:slug/versions/:version/confirm
• POST /:author/:slug/versions/:version/confirm
• GET /:author/:slug/versions/recommended/download
• GET /:author/:slug/versions/:version/download
• GET /:author/:slug/versions/recommended/jar
• GET /:author/:slug/versions/:version/jar
• GET /:author/:slug/versions/new
• POST /:author/:slug/versions/new/upload
• GET /:author/:slug/versions/new/:version
• POST /:author/:slug/versions/:version
• GET /:author/:slug/versions/:version
• POST /:author/:slug/versions/:version/save
• POST /:author/:slug/versions/:version/recommended

Reviews

• GET /:author/:slug/versions/:version/reviews
• POST /:author/:slug/versions/:version/reviews/init
• POST /:author/:slug/versions/:version/reviews/stop
• POST /:author/:slug/versions/:version/reviews/approve
• POST /:author/:slug/versions/:version/reviews/takeover
• POST /:author/:slug/versions/:version/reviews/addmessage
• POST /:author/:slug/versions/:version/reviews/edit/:review This actually has no function
• POST /:author/:slug/versions/:version/reviews/reopen
• POST /:author/:slug/versions/:version/reviews/reviewtoggle

Version Reviews - add link back to version

On the version reviews page, there isn't a link back to the version or project page. There probably should be for ease of use.

API Consolidation

Before beta, we need to consolidate v1 and v2 APIs. it really makes no sense to start with two api versions. There are a bunch of v1 api routes that aren't even used in the frontend.

v1 to be removed

/v1/projects - listProjects - v2 has has equivalent
/v1/projects/{author}/{slug} - showProject - v2 already has equivalent
/v1/projects/{author}/{slug}/pages - listPages - was used the the project page card, but was restructured to not need this anymore
/v1/projects/{author}/{slug}/versions - listVersions - v2 has equivalent
/v1/projects/{author}/{slug}/versions/{name:.*} - showVersion - v2 has equivalent
/v1/projects/{author}/{slug}/versions/{name:.*} - deployVersion - v2 has equivalent
/v1/projects/{author}/{slug}/tags/{name:.*} - listTags - included in v2 version of above
/v1/tags/{tagId} - not needed
/v1/users - dont see this used anywhere? does v2 need to have something to just get all users?
/v1/users/{user} - showUser - v2 has equivalent

v1 to be replaced

/v1/projects/{author}/{slug}/keys/new - (atm, its used for deployment key creation in project settings, will be replaced)
/v1/projects/{author}/{slug}/keys/revoke - (same as above)
/v1/platforms - maybe can just be replaced by putting info on window global object? currently used in DependencySelection.vue