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_export]
macro_rules! message { macro_rules! message {
($name:ident wraps $value:ty) => { ($name:ident: $value:ty: $docs:literal) => {
git_next_config::newtype!($name is a $value); git_next_config::newtype!($name: $value: $docs);
impl actix::prelude::Message for $name { impl actix::prelude::Message for $name {
type Result = (); type Result = ();
} }
}; };
($name:ident) => { ($name:ident: $docs:literal) => {
git_next_config::newtype!($name); git_next_config::newtype!($name: $docs);
impl actix::prelude::Message for $name { impl actix::prelude::Message for $name {
type Result = (); type Result = ();
} }
}; };
($name:ident wraps $value:ty => $result:ty) => { ($name:ident: $value:ty => $result:ty: $docs:literal) => {
git_next_config::newtype!($name is a $value); git_next_config::newtype!($name is a $value: $docs);
impl actix::prelude::Message for $name { impl actix::prelude::Message for $name {
type Result = $result; type Result = $result;
} }
}; };
($name:ident => $result:ty) => { ($name:ident => $result:ty: $docs:literal) => {
git_next_config::newtype!($name); git_next_config::newtype!($name: $docs);
impl actix::prelude::Message for $name { impl actix::prelude::Message for $name {
type Result = $result; type Result = $result;
} }

View file

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

View file

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

View file

@ -1,7 +1,7 @@
// //
use std::path::PathBuf; 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 { impl GitDir {
pub const fn pathbuf(&self) -> &PathBuf { pub const fn pathbuf(&self) -> &PathBuf {
&self.0 &self.0

View file

@ -1,2 +1,2 @@
// The hostname of a forge // 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_export]
macro_rules! newtype { macro_rules! newtype {
($name:ident) => { ($name:ident: $docs:literal) => {
#[doc = $docs]
#[derive( #[derive(
Clone, Clone,
Copy, Copy,
@ -15,15 +16,12 @@ macro_rules! newtype {
Ord, Ord,
Hash, Hash,
derive_more::AsRef, derive_more::AsRef,
derive_more::Constructor,
)] )]
pub struct $name; 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( #[derive(
Clone, Clone,
Debug, Debug,

View file

@ -2,6 +2,6 @@ use derive_more::Display;
use crate::newtype; use crate::newtype;
// The alias of a repo newtype!(RepoAlias: String, Display, Default: r#"The alias of a repo.
// This is the alias for the repo within `git-next-server.toml`
newtype!(RepoAlias is a String, Display, Default); 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: String, serde::Serialize: "The URL for the webhook where forges should send their updates");
newtype!(WebhookUrl is a String, serde::Serialize);
/// The directory to store server data, such as cloned repos /// The directory to store server data, such as cloned repos
#[derive( #[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 { impl WebhookAuth {
pub fn try_new(authorisation: &str) -> Result<Self, ulid::DecodeError> { pub fn try_new(authorisation: &str) -> Result<Self, ulid::DecodeError> {
use std::str::FromStr as _; 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!(Sha: String, Display, Hash: "The unique SHA for a git commit.");
newtype!(Message is a String, Hash); newtype!(Message: String, Hash: "The commit message for a git commit.");
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
pub struct Histories { pub struct Histories {

View file

@ -1,7 +1,9 @@
use derive_more::Display; use derive_more::Display;
use git_next_config::newtype; 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 { impl Generation {
pub fn inc(&mut self) { pub fn inc(&mut self) {
self.0 += 1 self.0 += 1

View file

@ -5,7 +5,7 @@ use git_next_config::newtype;
use crate::Commit; 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 { impl From<Commit> for GitRef {
fn from(value: Commit) -> Self { fn from(value: Commit) -> Self {
Self(value.sha().to_string()) 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_config as config;
use git_next_git as git; use git_next_git as git;
message!(LoadConfigFromRepo); message!(LoadConfigFromRepo: "Request to load the `git-next.toml` from the git repo.");
message!(CloneRepo); message!(CloneRepo: "Request to clone (or open) the git repo.");
message!(ReceiveRepoConfig wraps config::RepoConfig); message!(ReceiveRepoConfig: config::RepoConfig: r#"Notification that the `git-next.toml` file has been loaded from the repo and parsed.
message!(ValidateRepo wraps MessageToken);
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 { impl WebhookRegistered {
pub const fn webhook_id(&self) -> &config::WebhookId { pub const fn webhook_id(&self) -> &config::WebhookId {
&self.0 .0 &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 { impl MessageToken {
pub const fn next(&self) -> Self { pub const fn next(&self) -> Self {
Self(self.0 + 1) Self(self.0 + 1)
} }
} }
message!(RegisterWebhook); message!(RegisterWebhook: "Requests that a Webhook be registered with the forge.");
message!(CheckCIStatus wraps git::Commit); // next commit message!(CheckCIStatus: git::Commit: r#"Requests that the CI status for the commit be checked.
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 Once the CI Status has been received it will be sent via a [ReceiveCIStatus] message.
message!(AdvanceMain wraps git::Commit); // next commit
message!(WebhookNotification wraps config::webhook::forge_notification::ForgeNotification); 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 { impl Handler<ExamineActor> for RepoActor {
type Result = RepoActorView; type Result = RepoActorView;