From 986c5cebdee5aa53636ec4e900e11b01a89a738f Mon Sep 17 00:00:00 2001 From: Leon Hoppe Date: Thu, 21 Nov 2024 16:15:18 +0100 Subject: [PATCH] Added inline documentation + fixed small bugs --- docs/README.md | 21 ++- docs/models.md | 121 --------------- docs/services.md | 145 ------------------ docs/usage.md | 70 --------- src/HopFrame.Api/Logic/IAuthLogic.cs | 9 ++ src/HopFrame.Api/Models/SingleValueResult.cs | 5 + .../Repositories/IPermissionRepository.cs | 2 +- .../Repositories/ITokenRepository.cs | 6 +- .../Models/AdminPageProperty.cs | 2 - src/HopFrame.Web/AuthMiddleware.cs | 5 +- src/HopFrame.Web/HopAdminContext.cs | 2 +- .../Pages/Administration/AdminDashboard.razor | 3 + .../Administration/Layout/AdminMenu.razor | 5 +- 13 files changed, 37 insertions(+), 359 deletions(-) delete mode 100644 docs/models.md delete mode 100644 docs/services.md delete mode 100644 docs/usage.md diff --git a/docs/README.md b/docs/README.md index eb4fa47..582a4f0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,13 +1,10 @@ -# HopFrame documentation -These sides contain all documentation available for the HopFrame modules +# HopFrame Documentation -## Content -| Topic | Description | Document | -|----------|------------------------------------------------|-----------------------| -| Models | All models used by the HopFrame | [link](./models.md) | -| Services | All services provided by the HopFrame | [link](./services.md) | -| Usage | How to properly implement the HopFrame modules | [link](./usage.md) | - -## Dependencies -Both the HopFrame.Api and HopFrame.Web modules are dependent on the HopFrame.Database and HopFrame.Security modules. -So all models and services provided by these modules are available in the other modules as well. +- [x] In code documentation +- [ ] Installation +- [ ] Database usage +- [ ] Authentication usage +- [ ] LogicResult usage +- [ ] Repositories usage +- [ ] AuthService usage +- [ ] AdminPages usage diff --git a/docs/models.md b/docs/models.md deleted file mode 100644 index b8963eb..0000000 --- a/docs/models.md +++ /dev/null @@ -1,121 +0,0 @@ -# Models for HopFrame - -This page shows all models that HopFrame uses. - - -## Base Models -These are the models used by the various database services. - -```plantuml -@startuml -set namespaceSeparator none - -namespace HopFrame.Database { - class User { - +Id: Guid - +Username: string - +Email: string - +CreatedAt: DateTime - +Permissions: IList - } - - class Permission { - +Id: long - +PermissionName: string - +Owner: Guid - +GrantedAt: DateTime - } - - class PermissionGroup { - +Name: string - +IsDefaultGroup: bool - +Description: string - +CreatedAt: DateTime - +Permissions: IList - } - - interface IPermissionOwner {} -} - -IPermissionOwner <|-- User -IPermissionOwner <|-- PermissionGroup - -User .. Permission -PermissionGroup .. Permission -@enduml -``` - - -## API Models -These are the models used by the REST API and the Blazor API. - -```plantuml -@startuml -namespace HopFrame.Security { - class UserLogin { - +Email: string - +Password: string - } - - class UserRegister { - +Username: string - +Email: string - +Password: string - } -} - -namespace HopFrame.Api { - class SingleValueResult { - +Value: TValue - } - - class UserPasswordValidation { - +Password: string - } -} -@enduml -``` - - -## Database Models -These are the models that correspond to the scheme in the Database - -```plantuml -@startuml -set namespaceSeparator none - -namespace HopFrame.Database { - class UserEntry { - +Id: string - +Username: string - +Email: string - +Password: string - +CreatedAt: DateTime - } - - class TokenEntry { - +Type: int - +Token: string - +UserId: string - +CreatedAt: DateTime - } - - class PermissionEntry { - +RecordId: long - +PermissionText: string - +UserId: string - +GrantedAt: DateTime - } - - class GroupEntry { - +Name: string - +Default: bool - +Description: string - +CreatedAt: DateTime - } -} - -UserEntry *-- TokenEntry -UserEntry *-- PermissionEntry -@enduml -``` diff --git a/docs/services.md b/docs/services.md deleted file mode 100644 index 81a7312..0000000 --- a/docs/services.md +++ /dev/null @@ -1,145 +0,0 @@ -# HopFrame Services -This page describes all services provided by the HopFrame. -You can use these services by specifying them as a dependency. All of them are scoped dependencies. - -## HopFrame.Security -### ITokenContext -This service provides the information given by the current request - -```csharp -public interface ITokenContext { - bool IsAuthenticated { get; } - - User User { get; } - - Guid AccessToken { get; } -} -``` - -### IUserService -This service simplifies the data access of the user table in the database. - -```csharp -public interface IUserService { - Task> GetUsers(); - - Task GetUser(Guid userId); - - Task GetUserByEmail(string email); - - Task GetUserByUsername(string username); - - Task AddUser(UserRegister user); - - Task UpdateUser(User user); - - Task DeleteUser(User user); - - Task CheckUserPassword(User user, string password); - - Task ChangePassword(User user, string password); -} -``` - -### IPermissionService -This service handles all permission and group interactions with the data source. - -```csharp -public interface IPermissionService { - Task HasPermission(string permission, Guid user); - - Task> GetPermissionGroups(); - - Task GetPermissionGroup(string name); - - Task EditPermissionGroup(PermissionGroup group); - - Task> GetUserPermissionGroups(User user); - - Task RemoveGroupFromUser(User user, PermissionGroup group); - - Task CreatePermissionGroup(string name, bool isDefault = false, string description = null); - - Task DeletePermissionGroup(PermissionGroup group); - - Task GetPermission(string name, IPermissionOwner owner); - - Task AddPermission(IPermissionOwner owner, string permission); - - Task RemovePermission(Permission permission); - - Task GetFullPermissions(string user); -} -``` - -## HopFrame.Api -### LogicResult -Logic result is an extension of the ActionResult for an ApiController. It provides simple Http status results with either a message or data by specifying the generic type. - -```csharp -public class LogicResult : ILogicResult { - public static LogicResult Ok(); - - public static LogicResult BadRequest(); - - public static LogicResult BadRequest(string message); - - public static LogicResult Forbidden(); - - public static LogicResult Forbidden(string message); - - public static LogicResult NotFound(); - - public static LogicResult NotFound(string message); - - public static LogicResult Conflict(); - - public static LogicResult Conflict(string message); - - public static LogicResult Forward(LogicResult result); - - public static LogicResult Forward(ILogicResult result); - - public static implicit operator ActionResult(LogicResult v); -} - -public class LogicResult : ILogicResult { - public static LogicResult Ok(); - - public static LogicResult Ok(T result); - - ... -} -``` - -### IAuthLogic -This service handles all logic needed to provide the authentication endpoints by using the LogicResults. - -```csharp -public interface IAuthLogic { - Task>> Login(UserLogin login); - - Task>> Register(UserRegister register); - - Task>> Authenticate(); - - Task Logout(); - - Task Delete(UserPasswordValidation validation); -} -``` - -## HopFrame.Web -### IAuthService -This service handles all the authentication like login or register. It properly creates all tokens so the user can be identified - -```csharp -public interface IAuthService { - Task Register(UserRegister register); - Task Login(UserLogin login); - Task Logout(); - - Task RefreshLogin(); - Task IsLoggedIn(); -} -``` diff --git a/docs/usage.md b/docs/usage.md deleted file mode 100644 index 2023531..0000000 --- a/docs/usage.md +++ /dev/null @@ -1,70 +0,0 @@ -# HopFrame Usage -There are two different versions of HopFrame, either the Web API version or the full Blazor web version. - -## Ho to use the Web API version - -1. Add the HopFrame.Api library to your project: - - ``` - dotnet add package HopFrame.Api - ``` - -2. Create a DbContext that inherits the ``HopDbContext`` and add a data source - - ```csharp - public class DatabaseContext : HopDbContextBase { - protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { - base.OnConfiguring(optionsBuilder); - - optionsBuilder.UseSqlite("..."); - } - } - ``` - -3. Add the DbContext and HopFrame to your services - - ```csharp - builder.Services.AddDbContext(); - builder.Services.AddHopFrame(); - ``` - -## How to use the Blazor API - -1. Add the HopFrame.Web library to your project - - ``` - dotnet add package HopFrame.Web - ``` - -2. Create a DbContext that inherits the ``HopDbContext`` and add a data source - - ```csharp - public class DatabaseContext : HopDbContextBase { - protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { - base.OnConfiguring(optionsBuilder); - - optionsBuilder.UseSqlite("..."); - } - } - ``` - -3. Add the DbContext and HopFrame to your services - - ```csharp - builder.Services.AddDbContext(); - builder.Services.AddHopFrame(); - ``` - -4. Add the authentication middleware to your app - - ```csharp - app.UseMiddleware(); - ``` - -5. Add the HopFrame pages to your Razor components - - ```csharp - app.MapRazorComponents() - .AddHopFrameAdminPages() - .AddInteractiveServerRenderMode(); - ``` diff --git a/src/HopFrame.Api/Logic/IAuthLogic.cs b/src/HopFrame.Api/Logic/IAuthLogic.cs index 7dc5b78..3dd5b5b 100644 --- a/src/HopFrame.Api/Logic/IAuthLogic.cs +++ b/src/HopFrame.Api/Logic/IAuthLogic.cs @@ -8,9 +8,18 @@ public interface IAuthLogic { Task>> Register(UserRegister register); + /// + /// Reassures that the user has a valid refresh token and generates a new access token + /// + /// The newly generated access token Task>> Authenticate(); Task Logout(); + /// + /// Deletes the user account that called the endpoint if the provided password is correct + /// + /// The password od the user + /// Task Delete(UserPasswordValidation validation); } \ No newline at end of file diff --git a/src/HopFrame.Api/Models/SingleValueResult.cs b/src/HopFrame.Api/Models/SingleValueResult.cs index c09fdb6..81cbdb4 100644 --- a/src/HopFrame.Api/Models/SingleValueResult.cs +++ b/src/HopFrame.Api/Models/SingleValueResult.cs @@ -1,5 +1,10 @@ namespace HopFrame.Api.Models; +/// +/// Useful for endpoints that only return a single int or string +/// +/// The value of the result +/// The type of the result public struct SingleValueResult(TValue value) { public TValue Value { get; set; } = value; diff --git a/src/HopFrame.Database/Repositories/IPermissionRepository.cs b/src/HopFrame.Database/Repositories/IPermissionRepository.cs index 5971e34..07680ce 100644 --- a/src/HopFrame.Database/Repositories/IPermissionRepository.cs +++ b/src/HopFrame.Database/Repositories/IPermissionRepository.cs @@ -19,5 +19,5 @@ public interface IPermissionRepository { Task RemovePermission(IPermissionOwner owner, string permission); - public Task> GetFullPermissions(IPermissionOwner owner); + Task> GetFullPermissions(IPermissionOwner owner); } \ No newline at end of file diff --git a/src/HopFrame.Database/Repositories/ITokenRepository.cs b/src/HopFrame.Database/Repositories/ITokenRepository.cs index 19b38ac..bec3963 100644 --- a/src/HopFrame.Database/Repositories/ITokenRepository.cs +++ b/src/HopFrame.Database/Repositories/ITokenRepository.cs @@ -3,7 +3,7 @@ using HopFrame.Database.Models; namespace HopFrame.Database.Repositories; public interface ITokenRepository { - public Task GetToken(string content); - public Task CreateToken(int type, User owner); - public Task DeleteUserTokens(User owner); + Task GetToken(string content); + Task CreateToken(int type, User owner); + Task DeleteUserTokens(User owner); } \ No newline at end of file diff --git a/src/HopFrame.Web.Admin/Models/AdminPageProperty.cs b/src/HopFrame.Web.Admin/Models/AdminPageProperty.cs index 8347e36..60cc763 100644 --- a/src/HopFrame.Web.Admin/Models/AdminPageProperty.cs +++ b/src/HopFrame.Web.Admin/Models/AdminPageProperty.cs @@ -1,5 +1,3 @@ -using System.Text.Json.Serialization; - namespace HopFrame.Web.Admin.Models; public sealed class AdminPageProperty { diff --git a/src/HopFrame.Web/AuthMiddleware.cs b/src/HopFrame.Web/AuthMiddleware.cs index 509ad83..33e2f52 100644 --- a/src/HopFrame.Web/AuthMiddleware.cs +++ b/src/HopFrame.Web/AuthMiddleware.cs @@ -7,6 +7,9 @@ using Microsoft.AspNetCore.Http; namespace HopFrame.Web; +/// +/// Assures that the user stays logged in even if the access token is expired +/// public sealed class AuthMiddleware(IAuthService auth, IPermissionRepository perms) : IMiddleware { public async Task InvokeAsync(HttpContext context, RequestDelegate next) { var loggedIn = await auth.IsLoggedIn(); @@ -14,7 +17,7 @@ public sealed class AuthMiddleware(IAuthService auth, IPermissionRepository perm if (!loggedIn) { var token = await auth.RefreshLogin(); if (token is null) { - await next.Invoke(context); + next?.Invoke(context); return; } diff --git a/src/HopFrame.Web/HopAdminContext.cs b/src/HopFrame.Web/HopAdminContext.cs index e0ab493..22aac7b 100644 --- a/src/HopFrame.Web/HopAdminContext.cs +++ b/src/HopFrame.Web/HopAdminContext.cs @@ -8,7 +8,7 @@ using HopFrame.Web.Repositories; namespace HopFrame.Web; -public class HopAdminContext : AdminPagesContext { +internal class HopAdminContext : AdminPagesContext { public AdminPage Users { get; set; } public AdminPage Groups { get; set; } diff --git a/src/HopFrame.Web/Pages/Administration/AdminDashboard.razor b/src/HopFrame.Web/Pages/Administration/AdminDashboard.razor index 71d3482..7ebb3cf 100644 --- a/src/HopFrame.Web/Pages/Administration/AdminDashboard.razor +++ b/src/HopFrame.Web/Pages/Administration/AdminDashboard.razor @@ -5,11 +5,14 @@ @using BlazorStrap @using HopFrame.Web.Pages.Administration.Layout @using BlazorStrap.V5 +@using HopFrame.Security @using HopFrame.Web.Admin.Providers @using HopFrame.Web.Components @using Microsoft.AspNetCore.Components.Web @layout AdminLayout + + Admin Dashboard diff --git a/src/HopFrame.Web/Pages/Administration/Layout/AdminMenu.razor b/src/HopFrame.Web/Pages/Administration/Layout/AdminMenu.razor index aae2c7f..a47bafb 100644 --- a/src/HopFrame.Web/Pages/Administration/Layout/AdminMenu.razor +++ b/src/HopFrame.Web/Pages/Administration/Layout/AdminMenu.razor @@ -30,13 +30,12 @@ } - + logged in as @Context?.User.Username - + - logout