docs(server/config): add docs to types
All checks were successful
ci/woodpecker/push/push-next Pipeline was successful
ci/woodpecker/push/tag-created Pipeline was successful
ci/woodpecker/push/cron-docker-builder Pipeline was successful

This commit is contained in:
Paul Campbell 2024-04-13 11:31:00 +01:00
parent cfa25b7f67
commit 229d47f7c7

View file

@ -9,6 +9,7 @@ use terrors::OneOf;
use crate::filesystem::FileSystem; use crate::filesystem::FileSystem;
/// Mapped from the `git-next-server.toml` file
#[derive(Debug, PartialEq, Eq, Deserialize)] #[derive(Debug, PartialEq, Eq, Deserialize)]
pub struct ServerConfig { pub struct ServerConfig {
forge: HashMap<String, Forge>, forge: HashMap<String, Forge>,
@ -26,6 +27,9 @@ impl ServerConfig {
} }
} }
/// Mapped from `.git-next.toml` file in target repo
/// Is also derived from the optional parameters in `git-next-server.toml` at
/// `forge.{forge}.repos.{repo}.(main|next|dev)`
#[derive(Clone, Debug, PartialEq, Eq, Deserialize)] #[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
pub struct RepoConfig { pub struct RepoConfig {
branches: RepoBranches, branches: RepoBranches,
@ -45,6 +49,8 @@ impl Display for RepoConfig {
write!(f, "{:?}", self.branches) write!(f, "{:?}", self.branches)
} }
} }
/// Mapped from `.git-next.toml` file at `branches`
#[derive(Clone, Debug, PartialEq, Eq, Deserialize)] #[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
pub struct RepoBranches { pub struct RepoBranches {
main: String, main: String,
@ -70,6 +76,8 @@ impl Display for RepoBranches {
} }
} }
/// Defines a Forge to connect to
/// Maps from `git-next-server.toml` at `forge.{forge}`
#[derive(Clone, Debug, PartialEq, Eq, Deserialize)] #[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
pub struct Forge { pub struct Forge {
forge_type: ForgeType, forge_type: ForgeType,
@ -110,6 +118,8 @@ impl Display for Forge {
} }
} }
/// Defines a Repo within a Forge to be monitored by the server
/// Maps from `git-next-server.toml` at `forge.{forge}.repos.{name}`
#[derive(Clone, Debug, PartialEq, Eq, Deserialize)] #[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
pub struct Repo { pub struct Repo {
repo: String, repo: String,
@ -137,6 +147,8 @@ impl Display for Repo {
write!(f, "{} - {}", self.repo, self.branch) write!(f, "{} - {}", self.repo, self.branch)
} }
} }
/// The name of a Forge to connect to
#[derive(Clone, Debug, PartialEq, Eq)] #[derive(Clone, Debug, PartialEq, Eq)]
pub struct ForgeName(pub String); pub struct ForgeName(pub String);
impl Display for ForgeName { impl Display for ForgeName {
@ -144,6 +156,8 @@ impl Display for ForgeName {
write!(f, "{}", self.0) write!(f, "{}", self.0)
} }
} }
/// The hostname of a forge
#[derive(Clone, Debug, PartialEq, Eq)] #[derive(Clone, Debug, PartialEq, Eq)]
pub struct Hostname(pub String); pub struct Hostname(pub String);
impl Display for Hostname { impl Display for Hostname {
@ -151,6 +165,8 @@ impl Display for Hostname {
write!(f, "{}", self.0) write!(f, "{}", self.0)
} }
} }
/// The user within the forge to connect as
#[derive(Clone, Debug, PartialEq, Eq)] #[derive(Clone, Debug, PartialEq, Eq)]
pub struct User(pub String); pub struct User(pub String);
impl Display for User { impl Display for User {
@ -158,6 +174,10 @@ impl Display for User {
write!(f, "{}", self.0) write!(f, "{}", self.0)
} }
} }
/// The API Token for the [user]
/// ForgeJo: https://{hostname}/user/settings/applications
/// Github: https://github.com/settings/tokens
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
pub struct ApiToken(pub secrecy::Secret<String>); pub struct ApiToken(pub secrecy::Secret<String>);
impl From<String> for ApiToken { impl From<String> for ApiToken {
@ -165,11 +185,14 @@ impl From<String> for ApiToken {
Self(value.into()) Self(value.into())
} }
} }
/// The API Token is in effect a password, so it must be explicitly exposed to access its value
impl ExposeSecret<String> for ApiToken { impl ExposeSecret<String> for ApiToken {
fn expose_secret(&self) -> &String { fn expose_secret(&self) -> &String {
self.0.expose_secret() self.0.expose_secret()
} }
} }
/// The derived information about a Forge, used to create interactions with it
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
pub struct ForgeDetails { pub struct ForgeDetails {
pub name: ForgeName, pub name: ForgeName,
@ -191,6 +214,9 @@ impl From<(&ForgeName, &Forge)> for ForgeDetails {
} }
} }
} }
/// The name of a repo // TODO: (#39) rename as RepoAlias
/// This is the alias for the repo within `git-next-server.toml`
#[derive(Clone, Debug, PartialEq, Eq)] #[derive(Clone, Debug, PartialEq, Eq)]
pub struct RepoName(pub String); pub struct RepoName(pub String);
impl Display for RepoName { impl Display for RepoName {
@ -198,6 +224,10 @@ impl Display for RepoName {
write!(f, "{}", self.0) write!(f, "{}", self.0)
} }
} }
/// The path for the repo within the forge.
/// Typically this is composed of the user or organisation and the name of the repo
/// e.g. `{user}/{repo}`
#[derive(Clone, Debug, PartialEq, Eq)] #[derive(Clone, Debug, PartialEq, Eq)]
pub struct RepoPath(pub String); pub struct RepoPath(pub String);
impl Display for RepoPath { impl Display for RepoPath {
@ -205,6 +235,8 @@ impl Display for RepoPath {
write!(f, "{}", self.0) write!(f, "{}", self.0)
} }
} }
/// The name of a Branch
#[derive(Clone, Debug, Hash, PartialEq, Eq)] #[derive(Clone, Debug, Hash, PartialEq, Eq)]
pub struct BranchName(pub String); pub struct BranchName(pub String);
impl Display for BranchName { impl Display for BranchName {
@ -212,6 +244,8 @@ impl Display for BranchName {
write!(f, "{}", self.0) write!(f, "{}", self.0)
} }
} }
/// The derived information about a repo, used to interact with it
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
pub struct RepoDetails { pub struct RepoDetails {
pub name: RepoName, pub name: RepoName,
@ -251,6 +285,7 @@ impl Display for RepoDetails {
} }
} }
/// Identifier for the type of Forge
#[derive(Clone, Debug, PartialEq, Eq, Deserialize)] #[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
pub enum ForgeType { pub enum ForgeType {
#[cfg(feature = "forgejo")] #[cfg(feature = "forgejo")]