taler-rust

payto.rs (17173B)

---

 /*
   This file is part of TALER
   Copyright (C) 2024, 2025, 2026 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 3, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 */
 
 use std::{
     fmt::{Debug, Display},
     ops::{Deref, DerefMut},
     str::FromStr,
 };
 
 use compact_str::CompactString;
 use serde::{Deserialize, Serialize, de::DeserializeOwned};
 use serde_with::{DeserializeFromStr, SerializeDisplay};
 use url::Url;
 
 use super::{
     amount::Amount,
     iban::{BIC, IBAN},
 };
 
 /// Parse a payto URI, panic if malformed
 pub fn payto(url: impl AsRef<str>) -> PaytoURI {
     url.as_ref().parse().expect("invalid payto")
 }
 
 pub trait PaytoImpl: Sized {
     fn full(self, name: &str) -> FullPayto<Self> {
         FullPayto::new(self, name)
     }
 
     fn transfer(
         self,
         name: &str,
         amount: Option<Amount>,
         subject: Option<&str>,
     ) -> TransferPayto<Self> {
         TransferPayto::new(self, name, amount, subject)
     }
 
     fn as_uri(&self) -> PaytoURI;
     fn as_full_uri(&self, name: &str) -> PaytoURI {
         self.as_uri().as_full_payto(name)
     }
     fn as_transfer_uri(
         &self,
         name: &str,
         amount: Option<&Amount>,
         subject: Option<&str>,
     ) -> PaytoURI {
         self.as_uri().as_transfer_payto(name, amount, subject)
     }
     fn parse(uri: &PaytoURI) -> Result<Self, PaytoErr>;
 }
 
 /// A generic RFC 8905 payto URI
 #[derive(
     Debug, Clone, PartialEq, Eq, serde_with::DeserializeFromStr, serde_with::SerializeDisplay,
 )]
 pub struct PaytoURI(Url);
 
 impl PaytoURI {
     pub fn raw(&self) -> &str {
         self.0.as_str()
     }
 
     pub fn from_parts(domain: &str, path: impl Display) -> Self {
         payto(format!("payto://{domain}{path}"))
     }
 
     pub fn as_full_payto(self, name: &str) -> PaytoURI {
         self.with_query([("receiver-name", name)])
     }
 
     pub fn as_transfer_payto(
         self,
         name: &str,
         amount: Option<&Amount>,
         subject: Option<&str>,
     ) -> PaytoURI {
         self.as_full_payto(name)
             .with_query([("amount", amount)])
             .with_query([("message", subject)])
     }
 
     pub fn query<Q: DeserializeOwned>(&self) -> Result<Q, PaytoErr> {
         let query = self.0.query().unwrap_or_default().as_bytes();
         let de = serde_urlencoded::Deserializer::new(url::form_urlencoded::parse(query));
         serde_path_to_error::deserialize(de).map_err(PaytoErr::Query)
     }
 
     fn with_query(mut self, query: impl Serialize) -> Self {
         let mut urlencoder = self.0.query_pairs_mut();
         query
             .serialize(serde_urlencoded::Serializer::new(&mut urlencoder))
             .unwrap();
         let _ = urlencoder.finish();
         drop(urlencoder);
         self
     }
 }
 
 impl AsRef<Url> for PaytoURI {
     fn as_ref(&self) -> &Url {
         &self.0
     }
 }
 
 impl std::fmt::Display for PaytoURI {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         std::fmt::Display::fmt(self.raw(), f)
     }
 }
 
 #[derive(Debug, thiserror::Error)]
 pub enum PaytoErr {
     #[error("invalid payto URI: {0}")]
     Url(#[from] url::ParseError),
     #[error("malformed payto URI query: {0}")]
     Query(#[from] serde_path_to_error::Error<serde_urlencoded::de::Error>),
     #[error("expected a payto URI got {0}")]
     NotPayto(CompactString),
     #[error("unsupported payto kind, expected {0} got {1}")]
     UnsupportedKind(&'static str, CompactString),
     #[error("to much path segment for a {0} payto uri")]
     TooLong(&'static str),
     #[error("missing segment {0} in path")]
     MissingSegment(&'static str),
     #[error("malformed segment {0}: {1}")]
     MalformedSegment(
         &'static str,
         Box<dyn std::error::Error + Sync + Send + 'static>,
     ),
 }
 
 impl PaytoErr {
     pub fn malformed_segment<E: std::error::Error + Sync + Send + 'static>(
         segment: &'static str,
         e: E,
     ) -> Self {
         Self::MalformedSegment(segment, Box::new(e))
     }
 }
 
 impl FromStr for PaytoURI {
     type Err = PaytoErr;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         // Parse url
         let url: Url = s.parse()?;
         // Check scheme
         if url.scheme() != "payto" {
             return Err(PaytoErr::NotPayto(url.scheme().into()));
         }
         Ok(Self(url))
     }
 }
 
 pub type IbanPayto = Payto<BankID>;
 pub type FullIbanPayto = FullPayto<BankID>;
 pub type TransferIbanPayto = TransferPayto<BankID>;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct BankID {
     pub iban: IBAN,
     pub bic: Option<BIC>,
 }
 
 const IBAN: &str = "iban";
 
 impl PaytoImpl for BankID {
     fn as_uri(&self) -> PaytoURI {
         PaytoURI::from_parts(
             IBAN,
             format_args!(
                 "/{}",
                 std::fmt::from_fn(|f| {
                     if let Some(bic) = &self.bic {
                         write!(f, "{bic}/")?;
                     }
                     write!(f, "{}", self.iban)
                 })
             ),
         )
     }
 
     fn parse(raw: &PaytoURI) -> Result<Self, PaytoErr> {
         let url = raw.as_ref();
         if url.domain() != Some(IBAN) {
             return Err(PaytoErr::UnsupportedKind(
                 IBAN,
                 url.domain().unwrap_or_default().into(),
             ));
         }
         let Some(mut segments) = url.path_segments() else {
             return Err(PaytoErr::MissingSegment("iban"));
         };
         let Some(first) = segments.next() else {
             return Err(PaytoErr::MissingSegment("iban"));
         };
         let (iban, bic) = match segments.next() {
             Some(second) => (second, Some(first)),
             None => (first, None),
         };
 
         Ok(Self {
             iban: iban
                 .parse()
                 .map_err(|e| PaytoErr::malformed_segment("iban", e))?,
             bic: bic
                 .map(|bic| {
                     bic.parse()
                         .map_err(|e| PaytoErr::malformed_segment("bic", e))
                 })
                 .transpose()?,
         })
     }
 }
 
 impl PaytoImpl for IBAN {
     fn as_uri(&self) -> PaytoURI {
         PaytoURI::from_parts("iban", format_args!("/{self}"))
     }
 
     fn parse(raw: &PaytoURI) -> Result<Self, PaytoErr> {
         raw.as_ref().path_segments().unwrap_or("".split('/'));
         let payto = BankID::parse(raw)?;
         Ok(payto.iban)
     }
 }
 
 /// Full payto query
 #[derive(Debug, Clone, Deserialize)]
 pub struct FullQuery {
     #[serde(rename = "receiver-name")]
     receiver_name: CompactString,
 }
 
 /// Transfer payto query
 #[derive(Debug, Clone, Deserialize)]
 pub struct TransferQuery {
     #[serde(rename = "receiver-name")]
     receiver_name: CompactString,
     amount: Option<Amount>,
     message: Option<CompactString>,
 }
 
 /// Parsed payto query
 #[derive(Debug, Clone, Deserialize)]
 pub struct ParsedQuery {
     #[serde(rename = "receiver-name")]
     receiver_name: Option<CompactString>,
     amount: Option<Amount>,
     message: Option<CompactString>,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, DeserializeFromStr, SerializeDisplay)]
 pub struct Payto<P> {
     inner: P,
 }
 
 impl<P> Payto<P> {
     pub fn convert<T: From<P>>(self) -> Payto<T> {
         Payto {
             inner: self.inner.into(),
         }
     }
 }
 
 impl<P: PaytoImpl> Payto<P> {
     pub fn new(inner: P) -> Self {
         Self { inner }
     }
 
     pub fn as_uri(&self) -> PaytoURI {
         self.inner.as_uri()
     }
 
     pub fn into_inner(self) -> P {
         self.inner
     }
 }
 
 impl<P: PaytoImpl> TryFrom<&PaytoURI> for Payto<P> {
     type Error = PaytoErr;
 
     fn try_from(value: &PaytoURI) -> Result<Self, Self::Error> {
         Ok(Self::new(P::parse(value)?))
     }
 }
 
 impl<P: PaytoImpl> From<FullPayto<P>> for Payto<P> {
     fn from(value: FullPayto<P>) -> Payto<P> {
         Self::new(value.inner)
     }
 }
 
 impl<P: PaytoImpl> From<TransferPayto<P>> for Payto<P> {
     fn from(value: TransferPayto<P>) -> Payto<P> {
         Self::new(value.inner)
     }
 }
 
 impl<P: PaytoImpl> std::fmt::Display for Payto<P> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         std::fmt::Display::fmt(&self.as_uri(), f)
     }
 }
 
 impl<P: PaytoImpl> FromStr for Payto<P> {
     type Err = PaytoErr;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let payto: PaytoURI = s.parse()?;
         Self::try_from(&payto)
     }
 }
 
 impl<P: PaytoImpl> Deref for Payto<P> {
     type Target = P;
 
     fn deref(&self) -> &Self::Target {
         &self.inner
     }
 }
 
 impl<P: PaytoImpl> DerefMut for Payto<P> {
     fn deref_mut(&mut self) -> &mut Self::Target {
         &mut self.inner
     }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, DeserializeFromStr, SerializeDisplay)]
 pub struct FullPayto<P> {
     inner: P,
     pub name: CompactString,
 }
 
 impl<P: PaytoImpl> FullPayto<P> {
     pub fn new(inner: P, name: &str) -> Self {
         Self {
             inner,
             name: CompactString::new(name),
         }
     }
 
     pub fn as_uri(&self) -> PaytoURI {
         self.inner.as_full_uri(&self.name)
     }
 
     pub fn into_inner(self) -> P {
         self.inner
     }
 }
 
 impl<P> FullPayto<P> {
     pub fn convert<T: From<P>>(self) -> FullPayto<T> {
         FullPayto {
             inner: self.inner.into(),
             name: self.name,
         }
     }
 }
 
 impl<P: PaytoImpl> TryFrom<&PaytoURI> for FullPayto<P> {
     type Error = PaytoErr;
 
     fn try_from(value: &PaytoURI) -> Result<Self, Self::Error> {
         let payto = P::parse(value)?;
         let query: FullQuery = value.query()?;
         Ok(Self {
             inner: payto,
             name: query.receiver_name,
         })
     }
 }
 
 impl<P: PaytoImpl> From<TransferPayto<P>> for FullPayto<P> {
     fn from(value: TransferPayto<P>) -> FullPayto<P> {
         FullPayto {
             inner: value.inner,
             name: value.name,
         }
     }
 }
 
 impl<P: PaytoImpl> std::fmt::Display for FullPayto<P> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         std::fmt::Display::fmt(&self.as_uri(), f)
     }
 }
 
 impl<P: PaytoImpl> FromStr for FullPayto<P> {
     type Err = PaytoErr;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let raw: PaytoURI = s.parse()?;
         Self::try_from(&raw)
     }
 }
 
 impl<P: PaytoImpl> Deref for FullPayto<P> {
     type Target = P;
 
     fn deref(&self) -> &Self::Target {
         &self.inner
     }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, DeserializeFromStr, SerializeDisplay)]
 pub struct TransferPayto<P> {
     inner: P,
     pub name: CompactString,
     pub amount: Option<Amount>,
     pub subject: Option<CompactString>,
 }
 
 impl<P: PaytoImpl> TransferPayto<P> {
     pub fn new(inner: P, name: &str, amount: Option<Amount>, subject: Option<&str>) -> Self {
         Self {
             inner,
             name: CompactString::new(name),
             amount,
             subject: subject.map(CompactString::new),
         }
     }
 
     pub fn as_uri(&self) -> PaytoURI {
         self.inner
             .as_transfer_uri(&self.name, self.amount.as_ref(), self.subject.as_deref())
     }
 
     pub fn into_inner(self) -> P {
         self.inner
     }
 }
 
 impl<P: PaytoImpl> TryFrom<&PaytoURI> for TransferPayto<P> {
     type Error = PaytoErr;
 
     fn try_from(value: &PaytoURI) -> Result<Self, Self::Error> {
         let payto = P::parse(value)?;
         let query: TransferQuery = value.query()?;
         Ok(Self {
             inner: payto,
             name: query.receiver_name,
             amount: query.amount,
             subject: query.message,
         })
     }
 }
 
 impl<P: PaytoImpl> std::fmt::Display for TransferPayto<P> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         std::fmt::Display::fmt(&self.as_uri(), f)
     }
 }
 
 impl<P: PaytoImpl> FromStr for TransferPayto<P> {
     type Err = PaytoErr;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let raw: PaytoURI = s.parse()?;
         Self::try_from(&raw)
     }
 }
 
 impl<P: PaytoImpl> Deref for TransferPayto<P> {
     type Target = P;
 
     fn deref(&self) -> &Self::Target {
         &self.inner
     }
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, DeserializeFromStr, SerializeDisplay)]
 pub struct ParsedPayto<P> {
     inner: P,
     pub name: Option<CompactString>,
     pub amount: Option<Amount>,
     pub subject: Option<CompactString>,
 }
 
 impl<P: PaytoImpl> ParsedPayto<P> {
     pub fn new(
         inner: P,
         name: Option<&str>,
         amount: Option<Amount>,
         subject: Option<&str>,
     ) -> Self {
         Self {
             inner,
             name: name.map(CompactString::new),
             amount,
             subject: subject.map(CompactString::new),
         }
     }
 
     pub fn into_inner(self) -> P {
         self.inner
     }
 }
 
 impl<P: PaytoImpl> TryFrom<&PaytoURI> for ParsedPayto<P> {
     type Error = PaytoErr;
 
     fn try_from(value: &PaytoURI) -> Result<Self, Self::Error> {
         let payto = P::parse(value)?;
         let query: ParsedQuery = value.query()?;
         Ok(Self {
             inner: payto,
             name: query.receiver_name,
             amount: query.amount,
             subject: query.message,
         })
     }
 }
 
 impl<P: PaytoImpl> std::fmt::Display for ParsedPayto<P> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         std::fmt::Display::fmt(&self.as_uri(), f)
     }
 }
 
 impl<P: PaytoImpl> FromStr for ParsedPayto<P> {
     type Err = PaytoErr;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let raw: PaytoURI = s.parse()?;
         Self::try_from(&raw)
     }
 }
 
 impl<P: PaytoImpl> Deref for ParsedPayto<P> {
     type Target = P;
 
     fn deref(&self) -> &Self::Target {
         &self.inner
     }
 }
 
 #[cfg(test)]
 mod test {
     use std::str::FromStr as _;
 
     use crate::types::{
         amount::amount,
         iban::IBAN,
         payto::{FullPayto, Payto, TransferPayto},
     };
 
     #[test]
     pub fn parse() {
         let iban = IBAN::from_str("FR1420041010050500013M02606").unwrap();
 
         // Simple payto
         let simple_payto = Payto::new(iban);
         assert_eq!(
             simple_payto,
             Payto::from_str(&format!("payto://iban/{iban}")).unwrap()
         );
         assert_eq!(
             simple_payto,
             Payto::try_from(&simple_payto.as_uri()).unwrap()
         );
         assert_eq!(
             simple_payto,
             Payto::from_str(&simple_payto.as_uri().to_string()).unwrap()
         );
 
         // Full payto
         let full_payto = FullPayto::new(iban, "John Smith");
         assert_eq!(
             full_payto,
             FullPayto::from_str(&format!("payto://iban/{iban}?receiver-name=John+Smith")).unwrap()
         );
         assert_eq!(
             full_payto,
             FullPayto::try_from(&full_payto.as_uri()).unwrap()
         );
         assert_eq!(
             full_payto,
             FullPayto::from_str(&full_payto.as_uri().to_string()).unwrap()
         );
         assert_eq!(simple_payto, full_payto.clone().into());
 
         // Transfer simple payto
         let transfer_payto = TransferPayto::new(iban, "John Smith", None, None);
         assert_eq!(
             transfer_payto,
             TransferPayto::from_str(&format!("payto://iban/{iban}?receiver-name=John+Smith"))
                 .unwrap()
         );
         assert_eq!(
             transfer_payto,
             TransferPayto::try_from(&transfer_payto.as_uri()).unwrap()
         );
         assert_eq!(
             transfer_payto,
             TransferPayto::from_str(&transfer_payto.as_uri().to_string()).unwrap()
         );
         assert_eq!(full_payto, transfer_payto.clone().into());
 
         // Transfer full payto
         let transfer_payto = TransferPayto::new(
             iban,
             "John Smith",
             Some(amount("EUR:12")),
             Some("Wire transfer subject"),
         );
         assert_eq!(
             transfer_payto,
             TransferPayto::from_str(&format!("payto://iban/{iban}?receiver-name=John+Smith&amount=EUR:12&message=Wire+transfer+subject"))
                 .unwrap()
         );
         assert_eq!(
             transfer_payto,
             TransferPayto::try_from(&transfer_payto.as_uri()).unwrap()
         );
         assert_eq!(
             transfer_payto,
             TransferPayto::from_str(&transfer_payto.as_uri().to_string()).unwrap()
         );
         assert_eq!(full_payto, transfer_payto.clone().into());
 
         let malformed = FullPayto::<IBAN>::from_str(
             "payto://iban/CH0400766000103138557?receiver-name=NYM%20Technologies%SA",
         )
         .unwrap();
         assert_eq!(malformed.as_ref().to_string(), "CH0400766000103138557");
         assert_eq!(malformed.name, "NYM Technologies%SA");
     }
 }