From 0ebb795acf6f79b73ae86bb318d12f13f0e48982 Mon Sep 17 00:00:00 2001 From: Bilal Mahmoud Date: Thu, 7 Nov 2024 14:27:16 +0100 Subject: [PATCH] feat: split metadata and make it optional --- apps/hash-graph/libs/api/src/rpc/account.rs | 61 -------------------- apps/hash-graph/libs/api/src/rpc/auth.rs | 21 ------- apps/hash-graph/libs/api/src/rpc/echo.rs | 21 ------- libs/@local/harpc/server/examples/account.rs | 21 ------- libs/@local/harpc/service/src/lib.rs | 47 ++++++++++++++- libs/@local/harpc/service/src/metadata.rs | 10 ---- libs/@local/harpc/service/src/procedure.rs | 50 +++++++++++++++- 7 files changed, 92 insertions(+), 139 deletions(-) diff --git a/apps/hash-graph/libs/api/src/rpc/account.rs b/apps/hash-graph/libs/api/src/rpc/account.rs index 26b1f9881d5..bc3b038848f 100644 --- a/apps/hash-graph/libs/api/src/rpc/account.rs +++ b/apps/hash-graph/libs/api/src/rpc/account.rs @@ -100,7 +100,6 @@ pub mod meta { use frunk::HList; use harpc_service::{ Subsystem, - metadata::Metadata, procedure::{Procedure, ProcedureIdentifier}, }; use harpc_types::{procedure::ProcedureId, version::Version}; @@ -158,16 +157,6 @@ pub mod meta { major: 0x00, minor: 0x00, }; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } pub struct ProcedureCreateAccount; @@ -176,16 +165,6 @@ pub mod meta { type Subsystem = AccountSystem; const ID: ::ProcedureId = AccountProcedureId::CreateAccount; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } pub struct ProcedureCreateAccountGroup; @@ -195,16 +174,6 @@ pub mod meta { const ID: ::ProcedureId = AccountProcedureId::CreateAccountGroup; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } pub struct ProcedureCheckAccountGroupPermission; @@ -214,16 +183,6 @@ pub mod meta { const ID: ::ProcedureId = AccountProcedureId::CheckAccountGroupPermission; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } pub struct ProcedureAddAccountGroupMember; @@ -233,16 +192,6 @@ pub mod meta { const ID: ::ProcedureId = AccountProcedureId::AddAccountGroupMember; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } pub struct ProcedureRemoveAccountGroupMember; @@ -252,16 +201,6 @@ pub mod meta { const ID: ::ProcedureId = AccountProcedureId::RemoveAccountGroupMember; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } } diff --git a/apps/hash-graph/libs/api/src/rpc/auth.rs b/apps/hash-graph/libs/api/src/rpc/auth.rs index 5225dfc5e02..fff45e3e1d1 100644 --- a/apps/hash-graph/libs/api/src/rpc/auth.rs +++ b/apps/hash-graph/libs/api/src/rpc/auth.rs @@ -38,7 +38,6 @@ pub mod meta { use frunk::HList; use harpc_service::{ Subsystem, - metadata::Metadata, procedure::{Procedure, ProcedureIdentifier}, }; use harpc_types::{procedure::ProcedureId, version::Version}; @@ -78,16 +77,6 @@ pub mod meta { major: 0x00, minor: 0x00, }; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } pub struct ProcedureAuthenticate; @@ -97,16 +86,6 @@ pub mod meta { const ID: ::ProcedureId = AuthenticationProcedureId::Authenticate; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } } diff --git a/apps/hash-graph/libs/api/src/rpc/echo.rs b/apps/hash-graph/libs/api/src/rpc/echo.rs index 469871a1da3..4ccf4bc8356 100644 --- a/apps/hash-graph/libs/api/src/rpc/echo.rs +++ b/apps/hash-graph/libs/api/src/rpc/echo.rs @@ -35,7 +35,6 @@ pub mod meta { use frunk::HList; use harpc_service::{ Subsystem, - metadata::Metadata, procedure::{Procedure, ProcedureIdentifier}, }; use harpc_types::{procedure::ProcedureId, version::Version}; @@ -75,16 +74,6 @@ pub mod meta { major: 0x00, minor: 0x00, }; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } pub struct ProcedureEcho; @@ -93,16 +82,6 @@ pub mod meta { type Subsystem = EchoSystem; const ID: ::ProcedureId = EchoProcedureId::Echo; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } } diff --git a/libs/@local/harpc/server/examples/account.rs b/libs/@local/harpc/server/examples/account.rs index b8dda748fb6..a1ca1b9e280 100644 --- a/libs/@local/harpc/server/examples/account.rs +++ b/libs/@local/harpc/server/examples/account.rs @@ -24,7 +24,6 @@ use harpc_server::{Server, ServerConfig, router::RouterBuilder, serve::serve, se use harpc_service::{ Subsystem, SubsystemIdentifier, delegate::SubsystemDelegate, - metadata::Metadata, procedure::{Procedure, ProcedureIdentifier}, role, }; @@ -103,16 +102,6 @@ impl Subsystem for Account { major: 0x00, minor: 0x00, }; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } #[derive(serde::Serialize, serde::Deserialize)] @@ -124,16 +113,6 @@ impl Procedure for CreateAccount { type Subsystem = Account; const ID: ::ProcedureId = AccountProcedureId::CreateAccount; - - fn metadata() -> Metadata { - Metadata { - since: Version { - major: 0x00, - minor: 0x00, - }, - deprecation: None, - } - } } #[derive(Debug, Copy, Clone, PartialEq, Eq, thiserror::Error)] diff --git a/libs/@local/harpc/service/src/lib.rs b/libs/@local/harpc/service/src/lib.rs index c9e91d02054..87e20aa855e 100644 --- a/libs/@local/harpc/service/src/lib.rs +++ b/libs/@local/harpc/service/src/lib.rs @@ -5,7 +5,7 @@ use harpc_types::{ version::Version, }; -use self::{metadata::Metadata, procedure::ProcedureIdentifier}; +use self::{metadata::Deprecation, procedure::ProcedureIdentifier}; pub mod delegate; pub mod metadata; @@ -42,6 +42,15 @@ impl RefinedSubsystemIdentifier for ! { } } +#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] +pub struct SubsystemInformation { + pub descriptor: SubsystemDescriptor, + /// The deprecation information for subsystem. + pub deprecation: Option, + /// The initial version this subsystem was introduced in. + pub initial_version: Version, +} + pub trait Subsystem { type SubsystemId: SubsystemIdentifier; type ProcedureId: ProcedureIdentifier; @@ -52,6 +61,7 @@ pub trait Subsystem { const ID: Self::SubsystemId; const VERSION: Version; + /// Returns the descriptor for this subsystem. #[must_use] fn descriptor() -> SubsystemDescriptor { SubsystemDescriptor { @@ -60,5 +70,38 @@ pub trait Subsystem { } } - fn metadata() -> Metadata; + /// Returns the initial version in which this subsystem was introduced. + /// + /// This version represents the first release where the subsystem became available. + /// + /// By default, this returns the initial version of `0.0`. + #[must_use] + fn initial_version() -> Version { + Version { + major: 0x00, + minor: 0x00, + } + } + + /// Returns the deprecation information for this subsystem, if any. + /// + /// By default, this returns `None`, indicating that the procedure is not deprecated. + /// Override this method to specify deprecation information. + #[must_use] + fn deprecation() -> Option { + None + } + + /// Returns comprehensive information about the subsystem. + /// + /// This method aggregates various details about the subsystem, including its + /// descriptor, initial version, and deprecation status. + #[must_use] + fn information() -> SubsystemInformation { + SubsystemInformation { + descriptor: Self::descriptor(), + initial_version: Self::initial_version(), + deprecation: Self::deprecation(), + } + } } diff --git a/libs/@local/harpc/service/src/metadata.rs b/libs/@local/harpc/service/src/metadata.rs index c305d8542bb..d5e5e965202 100644 --- a/libs/@local/harpc/service/src/metadata.rs +++ b/libs/@local/harpc/service/src/metadata.rs @@ -10,13 +10,3 @@ pub struct Deprecation { /// The reason for deprecation. pub reason: Option<&'static str>, } - -/// Metadata containing version information for procedures and services. -#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] -pub struct Metadata { - /// The version at which the procedure/service was introduced. - pub since: Version, - - /// The deprecation information for the procedure/service. - pub deprecation: Option, -} diff --git a/libs/@local/harpc/service/src/procedure.rs b/libs/@local/harpc/service/src/procedure.rs index fd5ca4e8a2b..21c314650ec 100644 --- a/libs/@local/harpc/service/src/procedure.rs +++ b/libs/@local/harpc/service/src/procedure.rs @@ -1,7 +1,10 @@ use frunk::HCons; -use harpc_types::procedure::{ProcedureDescriptor, ProcedureId}; +use harpc_types::{ + procedure::{ProcedureDescriptor, ProcedureId}, + version::Version, +}; -use crate::{Subsystem, metadata::Metadata}; +use crate::{Subsystem, metadata::Deprecation}; /// A marker trait for procedures that are included in a service. /// @@ -20,11 +23,23 @@ pub trait ProcedureIdentifier: Sized { fn into_id(self) -> ProcedureId; } +#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] +pub struct ProcedureInformation { + pub descriptor: ProcedureDescriptor, + + /// The version at which the procedure was introduced. + pub since: Version, + + /// The deprecation information for the procedure. + pub deprecation: Option, +} + pub trait Procedure: Sized { type Subsystem: Subsystem>; const ID: ::ProcedureId; + /// Returns the descriptor for this procedure. #[must_use] fn descriptor() -> ProcedureDescriptor { ProcedureDescriptor { @@ -32,5 +47,34 @@ pub trait Procedure: Sized { } } - fn metadata() -> Metadata; + /// Returns the version at which this procedure was introduced. + /// + /// By default, this returns the initial version of the subsystem. + /// Override this method to specify a different introduction version. + #[must_use] + fn since() -> Version { + Self::Subsystem::initial_version() + } + + /// Returns the deprecation information for this procedure. + /// + /// By default, this returns `None`, indicating that the procedure is not deprecated. + /// Override this method to specify deprecation information. + #[must_use] + fn deprecation() -> Option { + None + } + + /// Returns comprehensive information about the procedure. + /// + /// This method aggregates the descriptor, introduction version, and deprecation status + /// of the procedure into a single `ProcedureInformation` struct. + #[must_use] + fn information() -> ProcedureInformation { + ProcedureInformation { + descriptor: Self::descriptor(), + since: Self::since(), + deprecation: Self::deprecation(), + } + } }