WIP: refactor: update macro signatures and add documentation
All checks were successful
ci/woodpecker/push/cron-docker-builder Pipeline was successful
ci/woodpecker/push/push-next Pipeline was successful
ci/woodpecker/push/tag-created Pipeline was successful

This commit is contained in:
Paul Campbell 2024-06-29 14:56:20 +01:00
parent 0fd33739c1
commit c618c0b00b
15 changed files with 64 additions and 45 deletions

View file

@ -1,25 +1,25 @@
#[macro_export]
macro_rules! message {
($name:ident wraps $value:ty) => {
git_next_config::newtype!($name is a $value);
($name:ident: $value:ty: $docs:literal) => {
git_next_config::newtype!($name: $value: $docs);
impl actix::prelude::Message for $name {
type Result = ();
}
};
($name:ident) => {
git_next_config::newtype!($name);
($name:ident: $docs:literal) => {
git_next_config::newtype!($name: $docs);
impl actix::prelude::Message for $name {
type Result = ();
}
};
($name:ident wraps $value:ty => $result:ty) => {
git_next_config::newtype!($name is a $value);
($name:ident: $value:ty => $result:ty: $docs:literal) => {
git_next_config::newtype!($name is a $value: $docs);
impl actix::prelude::Message for $name {
type Result = $result;
}
};
($name:ident => $result:ty) => {
git_next_config::newtype!($name);
($name:ident => $result:ty: $docs:literal) => {
git_next_config::newtype!($name: $docs);
impl actix::prelude::Message for $name {
type Result = $result;
}

View file

@ -1,2 +1 @@
// The name of a Branch
crate::newtype!(BranchName is a String, derive_more::Display, Default);
crate::newtype!(BranchName: String, derive_more::Display, Default: "The name of a Git branch");

View file

@ -1,5 +1,4 @@
// The name of a Forge to connect to
crate::newtype!(ForgeAlias is a String, Hash, derive_more::Display, Default);
crate::newtype!(ForgeAlias: String, Hash, derive_more::Display, Default: "The name of a Forge to connect to");
impl From<&ForgeAlias> for std::path::PathBuf {
fn from(value: &ForgeAlias) -> Self {
Self::from(&value.0)

View file

@ -1,7 +1,7 @@
//
use std::path::PathBuf;
crate::newtype!(GitDir is a PathBuf, Default);
crate::newtype!(GitDir: PathBuf, Default: "The path to the directory containing the git repository.");
impl GitDir {
pub const fn pathbuf(&self) -> &PathBuf {
&self.0

View file

@ -1,2 +1,2 @@
// The hostname of a forge
crate::newtype!(Hostname is a String, derive_more::Display, Default);
crate::newtype!(Hostname: String, derive_more::Display, Default: "The hostname for the forge");

View file

@ -1,7 +1,8 @@
//
#[macro_export]
macro_rules! newtype {
($name:ident) => {
($name:ident: $docs:literal) => {
#[doc = $docs]
#[derive(
Clone,
Copy,
@ -15,15 +16,12 @@ macro_rules! newtype {
Ord,
Hash,
derive_more::AsRef,
derive_more::Constructor,
)]
pub struct $name;
impl $name {
pub fn new() -> Self {
Self
}
}
};
($name:ident is a $type:ty $(, $derive:ty)*) => {
($name:ident: $type:ty $(, $derive:ty)*: $docs:literal) => {
#[doc = $docs]
#[derive(
Clone,
Debug,

View file

@ -2,6 +2,6 @@ use derive_more::Display;
use crate::newtype;
// The alias of a repo
// This is the alias for the repo within `git-next-server.toml`
newtype!(RepoAlias is a String, Display, Default);
newtype!(RepoAlias: String, Display, Default: r#"The alias of a repo.
This is the alias for the repo within `git-next-server.toml`."#);

View file

@ -126,8 +126,7 @@ impl Webhook {
}
}
// The RL for the webhook where forges should send their updates
newtype!(WebhookUrl is a String, serde::Serialize);
newtype!(WebhookUrl: String, serde::Serialize: "The URL for the webhook where forges should send their updates");
/// The directory to store server data, such as cloned repos
#[derive(

View file

@ -1,5 +1,7 @@
//
crate::newtype!(WebhookAuth is a ulid::Ulid, derive_more::Display);
crate::newtype!(WebhookAuth: ulid::Ulid, derive_more::Display: r#"The unique token authorisation for the webhook.
Each monitored repository has it's own unique token, and it is different each time `git-next` runs."#);
impl WebhookAuth {
pub fn try_new(authorisation: &str) -> Result<Self, ulid::DecodeError> {
use std::str::FromStr as _;

View file

@ -1,2 +1,2 @@
//
crate::newtype!(WebhookId is a String, derive_more::Display);
crate::newtype!(WebhookId: String, derive_more::Display: "The ID of the webhook, as returned by the forge when it is registered.");

View file

@ -37,8 +37,8 @@ impl From<config::webhook::Push> for Commit {
}
}
newtype!(Sha is a String, Display, Hash);
newtype!(Message is a String, Hash);
newtype!(Sha: String, Display, Hash: "The unique SHA for a git commit.");
newtype!(Message: String, Hash: "The commit message for a git commit.");
#[derive(Clone, Debug)]
pub struct Histories {

View file

@ -1,7 +1,9 @@
use derive_more::Display;
use git_next_config::newtype;
newtype!(Generation is a u32, Display, Default, Copy);
newtype!(Generation: u32, Display, Default, Copy: r#"A counter for the server generation.
This counter is increased by one each time the server restarts itself when the configuration file is updated."#);
impl Generation {
pub fn inc(&mut self) {
self.0 += 1

View file

@ -5,7 +5,7 @@ use git_next_config::newtype;
use crate::Commit;
newtype!(GitRef is a String, Display);
newtype!(GitRef: String, Display: "A git reference to a git commit.");
impl From<Commit> for GitRef {
fn from(value: Commit) -> Self {
Self(value.sha().to_string())

View file

@ -6,12 +6,22 @@ use git_next_actor_macros::message;
use git_next_config as config;
use git_next_git as git;
message!(LoadConfigFromRepo);
message!(CloneRepo);
message!(ReceiveRepoConfig wraps config::RepoConfig);
message!(ValidateRepo wraps MessageToken);
message!(LoadConfigFromRepo: "Request to load the `git-next.toml` from the git repo.");
message!(CloneRepo: "Request to clone (or open) the git repo.");
message!(ReceiveRepoConfig: config::RepoConfig: r#"Notification that the `git-next.toml` file has been loaded from the repo and parsed.
message!(WebhookRegistered wraps (config::WebhookId, config::WebhookAuth));
Contains the parsed contents of the `git-next.toml` file."#);
message!(ValidateRepo: MessageToken: r#"Request that the state of the branches in the git repo be assessed and generate any followup actions.
This is the main function of `git-next` where decisions are made on what branches need to be updated and when.
Contains a [MessageToken] to reduce duplicate messages being sent. Only messages with the latest [MessageToken] are handled,
all others are dropped."#);
message!(WebhookRegistered: (config::WebhookId, config::WebhookAuth): r#"Notification that a webhook has been registered with a forge.
Contains a tuple of the ID for the webhook returned from the forge, and the unique authorisation token that
incoming messages from the forge must provide."#);
impl WebhookRegistered {
pub const fn webhook_id(&self) -> &config::WebhookId {
&self.0 .0
@ -28,16 +38,26 @@ impl From<config::RegisteredWebhook> for WebhookRegistered {
}
}
newtype!(MessageToken is a u32, Copy, Default, Display);
newtype!(MessageToken: u32, Copy, Default, Display: r#"An incremental token used to identify the current set of messages.
Primarily used by [ValidateRepo] to reduce duplicate messages. The token is incremented when a new Webhook message is
received, marking that message the latest, and causing any previous messages still being processed to be dropped when
they next send a [ValidateRepo] message."#);
impl MessageToken {
pub const fn next(&self) -> Self {
Self(self.0 + 1)
}
}
message!(RegisterWebhook);
message!(CheckCIStatus wraps git::Commit); // next commit
message!(ReceiveCIStatus wraps (git::Commit, git::forge::commit::Status)); // commit and it's status
message!(AdvanceNext wraps (git::Commit, Vec<git::Commit>)); // next commit and the dev commit history
message!(AdvanceMain wraps git::Commit); // next commit
message!(WebhookNotification wraps config::webhook::forge_notification::ForgeNotification);
message!(RegisterWebhook: "Requests that a Webhook be registered with the forge.");
message!(CheckCIStatus: git::Commit: r#"Requests that the CI status for the commit be checked.
Once the CI Status has been received it will be sent via a [ReceiveCIStatus] message.
Contains the commit from the tip of the `next` branch."#); // next commit
message!(ReceiveCIStatus: (git::Commit, git::forge::commit::Status): r#"Notification of the status of the CI checks for the commit.
Contains a tuple of the commit that was checked (the tip of the `next` branch) and the status."#); // commit and it's status
message!(AdvanceNext: (git::Commit, Vec<git::Commit>)); // next commit and the dev commit history
message!(AdvanceMain: git::Commit); // next commit
message!(WebhookNotification: config::webhook::forge_notification::ForgeNotification);

View file

@ -68,7 +68,7 @@ impl RepoActorLog {
}
}
message!(ExamineActor => RepoActorView);
message!(ExamineActor => RepoActorView: "Request a view of the current state of the [RepoActor].");
impl Handler<ExamineActor> for RepoActor {
type Result = RepoActorView;