|
1 | | -# EvaModuleRepositoryServer: a Code/Artifact-agnostic repository server for Release Management with simple user authentication. |
| 1 | +# EvaModuleRepositoryServer |
2 | 2 |
|
3 | | -This file explains the project structure, runtime flows, and conventions so you could understand the design and the reason behind this project. |
| 3 | +A Go REST server that manages modules and releases with filesystem-backed artifacts and a GORM-backed database. This repository provides a lightweight release-management backend with simple authentication, role/permission checks, and file storage for releases. |
4 | 4 |
|
5 | | -## 0) Check the test files under the `tests` folder so you easily grasp the Business Logic! |
| 5 | +**Quick highlights:** |
| 6 | +- **HTTP API**: Built with Gin. |
| 7 | +- **DB**: GORM for data persistence. |
| 8 | +- **File storage**: Releases and module artifacts stored on disk (configurable folders). |
| 9 | +- **Auth & Permissions**: JWT-based middleware and permission checks. |
6 | 10 |
|
7 | | -## 1) Big picture |
8 | | -- What: A Go (module) REST server using Gin that manages "modules" and "releases" with file storage and a GORM-backed DB. |
9 | | -- Major components: `cmd/server` (bootstrap), `internal/backend` (wires services/repos), `internal/routes` (endpoint mapping), `internal/handlers` (HTTP controllers), `internal/services` (business logic + transactions), `internal/repositories` (DB via GORM), `internal/models` (domain objects) and `pkg/*` (utils, logger, runtime helpers). |
| 11 | +**Table of contents** |
| 12 | +- Overview |
| 13 | +- Features |
| 14 | +- Architecture |
| 15 | +- API Quickstart & Reference |
| 16 | +- Getting started |
| 17 | +- Configuration |
| 18 | +- Development conventions |
| 19 | +- Testing |
| 20 | +- Useful files |
| 21 | +- Contributing |
10 | 22 |
|
11 | | -## 2) Core runtime & workflows |
12 | | -- Start server: run from repo root so config loader finds `internal/config/application.properties`: |
13 | | - - `go run main.go` (development) |
14 | | - - build binary: `go build ./...` then run. |
15 | | -- Tests: `go test ./...` or `go test ./tests -run TestName` or `make testCoverage`. |
16 | | -- Properties: configuration keys used by services: `module_folder`, `release_folder`, `dev_folder`, `server_port` and logging/JWT settings. The ConfigReader loads `internal/config/application.properties` using `os.Getwd()` so run commands from repo root or use InitializeWithPropertiesPath/Map helpers in `cmd/server` for tests. |
| 23 | +## Overview |
17 | 24 |
|
18 | | -## 3) Key patterns & conventions (project-specific) |
19 | | -- Thin handlers: `internal/handlers/*` parse requests and call `internal/services/*`. Prefer adding logic to services, not handlers. Example: `internal/handlers/modulehandler.go` delegates to `ModuleService`. |
20 | | -- Transactional methods: services expose `FooTx` variants that accept a GORM `tx` (use `utils.WithGormTransaction`/`repo.GetDB()` pattern). See `internal/services/moduleservice.go` for `CreateModuleTx`. |
21 | | -- File storage: modules/releases are stored on disk. Paths are derived from properties and helpers in `ModuleService` (`module_folder`, `release_folder`, `dev_folder`). Use `c.SaveUploadedFile(...)` and `utils.CreateFolder` consistently. |
22 | | -- Permissions / auth: endpoints use middleware `AuthMiddleWare` (`internal/middleware`) and permission enums in `internal/models`. Routes show middleware usage: `internal/routes/router.go` (e.g., `PreAuthorize(HasPermissions(...))`). Use `be.GetJWTSecret()` where middleware requires the secret. |
23 | | -- DTOs: handlers often return DTOs (under `internal/dto`) rather than raw models. Example: `ModuleService.FindByID` returns `dto.ModuleDTO`. |
24 | | -- Response helpers: use `pkg/utils` helpers `OkWithMessage` / `Err` for consistent JSON responses. |
| 25 | +EvaModuleRepositoryServer exposes REST endpoints to manage `modules` and `releases`. It supports creating modules, uploading releases (files), listing/searching, and basic user/permission management. The codebase is organized by handlers, services, repositories, and models to keep handlers thin and business logic in services. |
25 | 26 |
|
26 | | -## 4) DB & repo conventions |
27 | | -- Repositories wrap GORM operations and expose `GetDB()` for transactions. Mutating flows typically call repository `CreateTx/UpdateTx` inside transactions defined in services. |
| 27 | +## Features |
28 | 28 |
|
29 | | -## 5) Logging & errors |
30 | | -- Create loggers via `pkg/runtime/loggerfactory.go` and use `pkg/logger.ILogger`. Services use `runtime.CreateLogger(p)`. |
| 29 | +- Module management: create, update, list, and view modules. |
| 30 | +- Release management: upload/download release artifacts, release metadata, and status tracking. |
| 31 | +- File-based storage: release files persist to disk; paths are configurable. |
| 32 | +- Authentication & authorization: JWT middleware and role/permission checks for endpoints. |
| 33 | +- Transactional server-side operations: services provide transactional variants for DB + filesystem workflows. |
| 34 | +- Test resources: example test resources and utilities under the `tests` folder. |
31 | 35 |
|
32 | | -## 6) What to edit and how |
33 | | -- When adding features, add new handlers -> service -> repository layers. Keep handlers minimal; tests and complex logic belong in services. |
34 | | -- For multi-step operations touching DB + filesystem, implement a `Tx` service method that performs DB steps inside `WithGormTransaction`, prepare file paths, then persist files after transaction succeeds (see `CreateModuleTx`). |
| 36 | +## Architecture |
35 | 37 |
|
36 | | -## 7) Quick file references (examples) |
37 | | -- Route map: [internal/routes/router.go](internal/routes/router.go) |
38 | | -- Controller example: [internal/handlers/modulehandler.go](internal/handlers/modulehandler.go) |
39 | | -- Business logic & filesystem: [internal/services/moduleservice.go](internal/services/moduleservice.go) |
| 38 | +The project is layered for clarity and testability: |
| 39 | + |
| 40 | +- `cmd/server` : application bootstrap and wiring. |
| 41 | +- `internal/backend` : constructs services, repositories, and other dependencies. |
| 42 | +- `internal/routes` : route definitions and middleware registration. |
| 43 | +- `internal/handlers` : HTTP controllers (parse requests, validate input, return DTOs). |
| 44 | +- `internal/services` : business logic, transactions, filesystem coordination. |
| 45 | +- `internal/repositories` : GORM-based DB access; expose `GetDB()` for transactional work. |
| 46 | +- `internal/models` : domain objects and enums. |
| 47 | +- `internal/dto` : response/request DTOs used by handlers. |
| 48 | +- `pkg/*` : utilities, logger factory, and helpers (filesystem, utils, SQL helpers). |
| 49 | + |
| 50 | +Design notes: |
| 51 | + |
| 52 | +- Handlers should remain thin — most logic belongs in services. |
| 53 | +- Multi-step operations that touch DB and filesystem should use the service `Tx` pattern (use `utils.WithGormTransaction` and repository `GetDB()` to obtain a `tx`). |
| 54 | + |
| 55 | +## Getting started |
| 56 | + |
| 57 | +From the repository root (this is important because the config loader uses `os.Getwd()`): |
| 58 | + |
| 59 | +Development (direct): |
| 60 | + |
| 61 | +```bash |
| 62 | +go run main.go |
| 63 | +``` |
| 64 | + |
| 65 | +Build (direct): |
| 66 | + |
| 67 | +```bash |
| 68 | +go build ./... |
| 69 | +``` |
| 70 | + |
| 71 | +Makefile targets (convenience targets provided in the project `Makefile`): |
| 72 | + |
| 73 | +- `make run` : run the application (`go run main.go`) |
| 74 | +- `make build` : build the binary (`go build main.go`) |
| 75 | +- `make goClean` : run `go mod tidy` |
| 76 | +- `make clean` : remove generated `*.exe` files |
| 77 | +- `make testCoverage`: run tests with coverage for core packages and write `coverage.out` |
| 78 | +- `make showCoverage`: display the HTML coverage report from `coverage.out` |
| 79 | + |
| 80 | +You can run a make target like: |
| 81 | + |
| 82 | +```bash |
| 83 | +make run |
| 84 | +``` |
| 85 | + |
| 86 | +Run tests (direct): |
| 87 | + |
| 88 | +```bash |
| 89 | +go test ./... |
| 90 | +# or run specific tests |
| 91 | +go test ./tests -run TestName |
| 92 | +``` |
| 93 | + |
| 94 | +## Configuration |
| 95 | + |
| 96 | +Configuration is loaded from `internal/config/application.properties` by default. Key properties used by the application include: |
| 97 | + |
| 98 | +- `module_folder` : base path for module metadata files. |
| 99 | +- `release_folder` : base path where release artifacts are saved. |
| 100 | +- `dev_folder` : developer-specific storage (for local/dev flows). |
| 101 | +- `server_port` : HTTP server listen port. |
| 102 | +- JWT and logging settings: secret, expiry, log level. |
| 103 | + |
| 104 | +Test and helper functions support initializing config with an explicit properties map or path (see `cmd/server` test helpers). |
| 105 | + |
| 106 | +## Development conventions |
| 107 | + |
| 108 | +- Keep handlers minimal — delegate business logic to `internal/services`. |
| 109 | +- For DB changes that must be atomic with filesystem changes, implement a `*Tx` method in services and use `utils.WithGormTransaction`. |
| 110 | +- Use DTOs in `internal/dto` for handler responses rather than exposing GORM models directly. |
| 111 | +- Use `pkg/utils` response helpers (`OkWithMessage`, `Err`) for consistent JSON output. |
| 112 | + |
| 113 | +## Testing |
| 114 | + |
| 115 | +- Test resources are under `tests/test_resources`. |
| 116 | +- Use `InitializeWithPropertiesMap` utilities when you need to alter folders/ports for isolated tests. |
| 117 | +- Run `go test ./...` to execute all tests. |
| 118 | + |
| 119 | +## Useful files |
| 120 | + |
| 121 | +- Server entrypoint: [cmd/server/server.go](cmd/server/server.go) |
40 | 122 | - Config loader: [internal/config/configreader.go](internal/config/configreader.go) |
41 | | -- Server bootstrap: [cmd/server/server.go](cmd/server/server.go) |
42 | | -- Response helpers: [pkg/utils/utils.go](pkg/utils/utils.go) |
| 123 | +- Route map: [internal/routes/router.go](internal/routes/router.go) |
| 124 | +- Example handler: [internal/handlers/modulehandler.go](internal/handlers/modulehandler.go) |
| 125 | +- Core service: [internal/services/moduleservice.go](internal/services/moduleservice.go) |
| 126 | +- Repositories: [internal/repositories](internal/repositories) |
| 127 | +- Models and DTOs: [internal/models](internal/models) and [internal/dto](internal/dto) |
| 128 | +- Utils and helpers: [pkg/utils/utils.go](pkg/utils/utils.go), [pkg/runtime/loggerfactory.go](pkg/runtime/loggerfactory.go) |
| 129 | + |
| 130 | +## API Quickstart & Reference |
| 131 | + |
| 132 | +This section summarizes the HTTP API grouped by route and provides quick `curl` examples for common flows. |
| 133 | + |
| 134 | +### Auth (/api/auth) |
| 135 | + |
| 136 | +- `POST /api/auth/login` — `AuthHandler.Login` — obtain JWT |
| 137 | +- `POST /api/auth/refresh` — `AuthHandler.Refresh` — refresh token |
| 138 | +- `POST /api/auth/register` — `AuthHandler.Register` — create account |
| 139 | + |
| 140 | +Example: login |
| 141 | + |
| 142 | +```bash |
| 143 | +curl -X POST http://localhost:8080/api/auth/login \ |
| 144 | + -H "Content-Type: application/json" \ |
| 145 | + -d '{"username":"alice","password":"s3cret"}' |
| 146 | +# Response contains access token (JWT) |
| 147 | +``` |
| 148 | + |
| 149 | +--- |
| 150 | + |
| 151 | +### Modules (/api/modules) |
| 152 | + |
| 153 | +- `GET /api/modules/:id` — `ModuleHandler.FindByID` |
| 154 | +- `GET /api/modules/search` — `ModuleHandler.SearchModulesByTags` |
| 155 | +- `POST /api/modules/delete` — `ModuleHandler.Delete` (Auth + permissions) |
| 156 | +- `POST /api/modules/upload` — `ModuleHandler.Upload` (Auth + multipart + permissions) |
| 157 | +- `POST /api/modules/update` — `ModuleHandler.Update` (Auth + permissions) |
| 158 | +- `POST /api/modules/suggest` — `ModuleHandler.SuggestRelease` (Auth + permissions) |
| 159 | + |
| 160 | +Example: create/upload module (multipart) |
| 161 | + |
| 162 | +```bash |
| 163 | +# First obtain JWT from /api/auth/login, then use it in Authorization header |
| 164 | +curl -X POST http://localhost:8080/api/modules/upload \ |
| 165 | + -H "Authorization: Bearer $JWT" \ |
| 166 | + -F "metadata=@module.json;type=application/json" \ |
| 167 | + -F "file=@artifact.zip;type=application/zip" |
| 168 | +``` |
| 169 | + |
| 170 | +Example: search modules by tags |
| 171 | + |
| 172 | +```bash |
| 173 | +curl "http://localhost:8080/api/modules/search?tag=parser&tag=example" |
| 174 | +``` |
| 175 | + |
| 176 | +--- |
| 177 | + |
| 178 | +### Releases (/api/releases) |
| 179 | + |
| 180 | +- `GET /api/releases/:id` — `ReleaseHandler.GetModuleReleases` (list by module id) |
| 181 | +- `GET /api/releases/:id/release/:releaseId` — `ReleaseHandler.GetModuleRelease` (single release) |
| 182 | +- `GET /api/releases/:id/search` — `ReleaseHandler.SearchByKeywords` |
| 183 | +- `POST /api/releases/:id/delete/:releaseId` — `ReleaseHandler.DeleteModuleRelease` (Auth + permissions) |
| 184 | +- `POST /api/releases/:id/cancel/:releaseId` — `ReleaseHandler.CancelSuggestedRelease` (Auth + permissions) |
| 185 | + |
| 186 | +Example: list releases for module |
| 187 | + |
| 188 | +```bash |
| 189 | +curl http://localhost:8080/api/releases/123 |
| 190 | +``` |
| 191 | + |
| 192 | +--- |
| 193 | + |
| 194 | +### Download (/api/download) |
| 195 | + |
| 196 | +- `GET /api/download/release/:releaseId` — `DownloadHandler.DownloadRelease` (download accepted release) |
| 197 | + |
| 198 | +Example: download release |
| 199 | + |
| 200 | +```bash |
| 201 | +curl -L -o myrelease.zip http://localhost:8080/api/download/release/456 |
| 202 | +``` |
| 203 | + |
| 204 | +--- |
| 205 | + |
| 206 | +### Supervise (/api/supervise) |
| 207 | + |
| 208 | +All supervise endpoints require Auth + appropriate permission checks. |
| 209 | + |
| 210 | +- `GET /api/supervise/download/release/:releaseId` — `DownloadHandler.DownloadAnyRelease` (permission: `UpdateReleases`) |
| 211 | +- `POST /api/supervise/reject/release/:releaseId` — `ReleaseHandler.RejectRelease` (permission: `RejectReleases`) |
| 212 | +- `POST /api/supervise/accept/release/:releaseId` — `ReleaseHandler.AcceptRelease` (permission: `AcceptReleases`) |
| 213 | +- `POST /api/supervise/cancel/release/:releaseId` — `ReleaseHandler.CancelRelease` (permission: `CancelReleases`) |
| 214 | +- `POST /api/supervise/pending/release/:releaseId` — `ReleaseHandler.ChangeToPendingRelease` (permission: `CancelReleases`) |
| 215 | +- `POST /api/supervise/ban/:userId` — `SuperviseHandler.BanUser` (permissions: `BanUsers`, `UnbanUsers`) |
| 216 | +- `POST /api/supervise/unban/:userId` — `SuperviseHandler.UnbanUser` (permissions: `BanUsers`, `UnbanUsers`) |
| 217 | + |
| 218 | +Example: accept a pending release (supervisor) |
| 219 | + |
| 220 | +```bash |
| 221 | +curl -X POST http://localhost:8080/api/supervise/accept/release/456 \ |
| 222 | + -H "Authorization: Bearer $SUPERVISOR_JWT" |
| 223 | +``` |
| 224 | + |
| 225 | +--- |
| 226 | + |
| 227 | +### Notes and tips |
| 228 | + |
| 229 | +- The API base path is `/api`. |
| 230 | +- Default upload limit is 8 MB (adjustable in router code via `EvaModuleRepositoryRouter.SetUploadFileLimit`). |
| 231 | +- All protected endpoints require `Authorization: Bearer <JWT>` header. |
| 232 | +- Permission names are defined in `internal/models` (for example `AcceptReleases`, `DeleteMyModule`). |
| 233 | +- For handler implementation details, see `internal/handlers/*` and service logic in `internal/services/*`. |
| 234 | + |
| 235 | +--- |
| 236 | + |
| 237 | +## Contributing |
| 238 | + |
| 239 | +- Follow the existing project structure: handlers -> services -> repositories. |
| 240 | +- Add tests for new behavior and update `tests/test_resources` as needed. |
| 241 | +- Keep configuration usage consistent; prefer using provided helpers for tests. |
| 242 | + |
| 243 | +## License |
| 244 | + |
| 245 | +See the repository `LICENSE` file. |
| 246 | + |
| 247 | +--- |
43 | 248 |
|
44 | | -## 8) Testing notes |
45 | | -- Test utilities and resources are in `tests/test_resources`. For isolated tests, use `InitializeWithPropertiesMap` to override folders and ports. |
|
0 commit comments