asonix/activitystreams-new
2
1
Fork 0
Code Issues Pull requests Releases Wiki Activity

Document actor

Browse source
This commit is contained in:
asonix 2020-05-16 17:19:15 -05:00
parent d0c3cf46af
commit cd35672dc1
1 changed files with 489 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

490
src/actor.rs
View file

@ -1,3 +1,24 @@
//! Types and traits for dealing with Actor attributes
//!
//! ```rust
//! # fn main() -> Result<(), anyhow::Error> {
//! use activitystreams_new::{
//! actor::{ApActor, Person},
//! prelude::*,
//! primitives::XsdAnyUri,
//! };
//!
//! let mut person = ApActor::<Person>::default();
//!
//! person
//! .set_inbox("https://example.com/actor/inbox".parse()?)
//! .set_outbox("https://example.com/actor/outbox".parse()?)
//! .set_following("https://example.com/actor/following".parse()?)
//! .set_followers("https://example.com/actor/followers".parse()?);
//! #
//! # Ok(())
//! # }
//! ```
use crate::{
base::{AsBase, Base, Extends},
markers,
@ -8,17 +29,42 @@ use crate::{
use typed_builder::TypedBuilder;
pub mod kind {
//! Kinds of actors defined by the spec
//!
//! These types exist only to be statically-typed versions of the associated string. e.g.
//! `PersonType` -> `"Person"`
pub use activitystreams::actor::kind::*;
}
use self::kind::*;
/// Implementation trait for deriving ActivityPub Actor methods for a type
///
/// Any type implementing AsObject will automatically gain methods provided by ApActorExt
pub trait AsApActor<Inner>: markers::Actor {
/// Immutable borrow of `ApActor<Inner>`
fn ap_actor_ref(&self) -> &ApActor<Inner>;
/// Mutable borrow of `ApActor<Inner>`
fn ap_actor_mut(&mut self) -> &mut ApActor<Inner>;
}
/// Helper methods for interacting with ActivityPub Actor types
///
/// This trait represents methods valid for any ActivityPub Actor.
///
/// Documentation for the fields related to these methods can be found on the `ApActor` struct
pub trait ApActorExt<Inner>: AsApActor<Inner> {
/// Fetch the inbox for the current actor
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// let inbox_ref = person.inbox();
/// ```
fn inbox<'a>(&'a self) -> &'a XsdAnyUri
where
Inner: 'a,
@ -26,11 +72,32 @@ pub trait ApActorExt<Inner>: AsApActor<Inner> {
&self.ap_actor_ref().inbox
}
/// Set the inbox for the current actor
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// person.set_inbox("https://example.com/inbox".parse()?);
/// # Ok(())
/// # }
/// ```
fn set_inbox(&mut self, inbox: XsdAnyUri) -> &mut Self {
self.ap_actor_mut().inbox = inbox;
self
}
/// Fetch the outbox for the current actor
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// let outbox_ref = person.outbox();
/// ```
fn outbox<'a>(&'a self) -> &'a XsdAnyUri
where
Inner: 'a,
@ -38,11 +105,34 @@ pub trait ApActorExt<Inner>: AsApActor<Inner> {
&self.ap_actor_ref().outbox
}
/// Set the outbox for the current actor
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// person.set_outbox("https://example.com/outbox".parse()?);
/// # Ok(())
/// # }
/// ```
fn set_outbox(&mut self, outbox: XsdAnyUri) -> &mut Self {
self.ap_actor_mut().outbox = outbox;
self
}
/// Fetch the following link for the current actor
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(following) = person.following() {
/// println!("{:?}", following);
/// }
/// ```
fn following<'a>(&'a self) -> Option<&'a XsdAnyUri>
where
Inner: 'a,
@ -50,20 +140,69 @@ pub trait ApActorExt<Inner>: AsApActor<Inner> {
self.ap_actor_ref().following.as_ref()
}
/// Set the following link for the current actor
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// person.set_following("https://example.com/following".parse()?);
/// # Ok(())
/// # }
/// ```
fn set_following(&mut self, following: XsdAnyUri) -> &mut Self {
self.ap_actor_mut().following = Some(following);
self
}
/// Take the following link for the current actor, leaving nothing
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(following) = person.take_following() {
/// println!("{:?}", following);
/// }
/// ```
fn take_following(&mut self) -> Option<XsdAnyUri> {
self.ap_actor_mut().following.take()
}
/// Delete the following link from the current object
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// # person.set_following("https://example.com/following".parse()?);
/// use activitystreams_new::prelude::*;
///
/// assert!(person.following().is_some());
/// person.delete_following();
/// assert!(person.following().is_none());
/// # Ok(())
/// # }
/// ```
fn delete_following(&mut self) -> &mut Self {
self.ap_actor_mut().following = None;
self
}
/// Fetch the followers link for the current actor
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(followers) = person.take_followers() {
/// println!("{:?}", followers);
/// }
/// ```
fn followers<'a>(&'a self) -> Option<&'a XsdAnyUri>
where
Inner: 'a,
@ -71,20 +210,69 @@ pub trait ApActorExt<Inner>: AsApActor<Inner> {
self.ap_actor_ref().followers.as_ref()
}
/// Set the followers link for the current actor
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// person.set_followers("https://example.com/followers".parse()?);
/// # Ok(())
/// # }
/// ```
fn set_followers(&mut self, followers: XsdAnyUri) -> &mut Self {
self.ap_actor_mut().followers = Some(followers);
self
}
/// Take the followers link for the current actor, leaving nothing
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(followers) = person.take_followers() {
/// println!("{:?}", followers);
/// }
/// ```
fn take_followers(&mut self) -> Option<XsdAnyUri> {
self.ap_actor_mut().followers.take()
}
/// Delete the followers link from the current object
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// # person.set_followers("https://example.com/followers".parse()?);
/// use activitystreams_new::prelude::*;
///
/// assert!(person.followers().is_some());
/// person.delete_followers();
/// assert!(person.followers().is_none());
/// # Ok(())
/// # }
/// ```
fn delete_followers(&mut self) -> &mut Self {
self.ap_actor_mut().followers = None;
self
}
/// Fetch the liked link for the current actor
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(liked) = person.take_liked() {
/// println!("{:?}", liked);
/// }
/// ```
fn liked<'a>(&'a self) -> Option<&'a XsdAnyUri>
where
Inner: 'a,
@ -92,20 +280,69 @@ pub trait ApActorExt<Inner>: AsApActor<Inner> {
self.ap_actor_ref().liked.as_ref()
}
/// Set the liked link for the current actor
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// person.set_streams("https://example.com/liked".parse()?);
/// # Ok(())
/// # }
/// ```
fn set_liked(&mut self, liked: XsdAnyUri) -> &mut Self {
self.ap_actor_mut().liked = Some(liked);
self
}
/// Take the liked link for the current actor, leaving nothing
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(liked) = person.take_liked() {
/// println!("{:?}", liked);
/// }
/// ```
fn take_liked(&mut self) -> Option<XsdAnyUri> {
self.ap_actor_mut().liked.take()
}
/// Delete the liked link from the current object
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// # person.set_liked("https://example.com/liked".parse()?);
/// use activitystreams_new::prelude::*;
///
/// assert!(person.liked().is_some());
/// person.delete_liked();
/// assert!(person.liked().is_none());
/// # Ok(())
/// # }
/// ```
fn delete_liked(&mut self) -> &mut Self {
self.ap_actor_mut().liked = None;
self
}
/// Fetch the streams links for the current actor
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(streams) = person.take_streams() {
/// println!("{:?}", streams);
/// }
/// ```
fn streams<'a>(&'a self) -> Option<&'a OneOrMany<XsdAnyUri>>
where
Inner: 'a,
@ -113,11 +350,38 @@ pub trait ApActorExt<Inner>: AsApActor<Inner> {
self.ap_actor_ref().streams.as_ref()
}
/// Set the streams links for the current actor
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// person.set_streams("https://example.com/streams".parse()?);
/// # Ok(())
/// # }
/// ```
fn set_streams(&mut self, streams: XsdAnyUri) -> &mut Self {
self.ap_actor_mut().streams = Some(streams.into());
self
}
/// Set many streams links for the current actor
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// person.set_many_streams(vec![
/// "https://example.com/streams1".parse()?,
/// "https://example.com/streams2".parse()?
/// ]);
/// # Ok(())
/// # }
/// ```
fn set_many_streams<I>(&mut self, items: I) -> &mut Self
where
I: IntoIterator<Item = XsdAnyUri>,
@ -127,7 +391,21 @@ pub trait ApActorExt<Inner>: AsApActor<Inner> {
self
}
fn add_stream(&mut self, stream: XsdAnyUri) -> &mut Self {
/// Add a streams link for the current actor
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// person
/// .add_streams("https://example.com/streams1".parse()?)
/// .add_streams("https://example.com/streams2".parse()?);
/// # Ok(())
/// # }
/// ```
fn add_streams(&mut self, stream: XsdAnyUri) -> &mut Self {
let v = match self.ap_actor_mut().streams.take() {
Some(mut v) => {
v.add(stream);
@ -139,15 +417,52 @@ pub trait ApActorExt<Inner>: AsApActor<Inner> {
self
}
/// Take the streams links for the current actor, leaving nothing
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(streams) = person.take_streams() {
/// println!("{:?}", streams);
/// }
/// ```
fn take_streams(&mut self) -> Option<OneOrMany<XsdAnyUri>> {
self.ap_actor_mut().streams.take()
}
/// Delete the streams links from the current object
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// # person.set_streams("https://example.com/streams".parse()?);
/// use activitystreams_new::prelude::*;
///
/// assert!(person.streams().is_some());
/// person.delete_streams();
/// assert!(person.streams().is_none());
/// # Ok(())
/// # }
/// ```
fn delete_streams(&mut self) -> &mut Self {
self.ap_actor_mut().streams = None;
self
}
/// Fetch the preferred_username for the current actor
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(preferred_username) = person.preferred_username() {
/// println!("{:?}", preferred_username);
/// }
/// ```
fn preferred_username<'a>(&'a self) -> Option<&'a XsdString>
where
Inner: 'a,
@ -155,20 +470,66 @@ pub trait ApActorExt<Inner>: AsApActor<Inner> {
self.ap_actor_ref().preferred_username.as_ref()
}
/// Set the preferred_username for the current actor
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// person.set_preferred_username("user123".into());
/// # Ok(())
/// # }
/// ```
fn set_preferred_username(&mut self, string: XsdString) -> &mut Self {
self.ap_actor_mut().preferred_username = Some(string);
self
}
/// Take the preferred_username from the current actor, leaving nothing
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(preferred_username) = person.take_preferred_username() {
/// println!("{:?}", preferred_username);
/// }
/// ```
fn take_preferred_username(&mut self) -> Option<XsdString> {
self.ap_actor_mut().preferred_username.take()
}
/// Delete the preferred_username from the current actor
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// # person.set_preferred_username("hey".into());
/// use activitystreams_new::prelude::*;
///
/// assert!(person.preferred_username().is_some());
/// person.delete_preferred_username();
/// assert!(person.preferred_username().is_none());
/// ```
fn delete_preferred_username(&mut self) -> &mut Self {
self.ap_actor_mut().preferred_username = None;
self
}
/// Fetch the endpoints for the current actor
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(endpoints) = person.endpoints() {
/// println!("{:?}", endpoints);
/// }
/// ```
fn endpoints<'a>(&'a self) -> Option<&'a Endpoints>
where
Inner: 'a,
@ -176,15 +537,53 @@ pub trait ApActorExt<Inner>: AsApActor<Inner> {
self.ap_actor_ref().endpoints.as_ref()
}
/// Set the endpoints for the current actor
///
/// ```rust
/// # fn main() -> Result<(), anyhow::Error> {
/// # use activitystreams_new::actor::{ApActor, Endpoints, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// person.set_endpoints(Endpoints {
/// shared_inbox: Some("https://example.com/inbox".parse()?),
/// ..Default::default()
/// });
/// # Ok(())
/// # }
/// ```
fn set_endpoints(&mut self, endpoints: Endpoints) -> &mut Self {
self.ap_actor_mut().endpoints = Some(endpoints);
self
}
/// Take the endpoints from the current actor, leaving nothing
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// use activitystreams_new::prelude::*;
///
/// if let Some(endpoints) = person.endpoints() {
/// println!("{:?}", endpoints);
/// }
/// ```
fn take_endpoints(&mut self) -> Option<Endpoints> {
self.ap_actor_mut().endpoints.take()
}
/// Delete the endpoints from the current actor
///
/// ```rust
/// # use activitystreams_new::actor::{ApActor, Person};
/// # let mut person = ApActor::<Person>::default();
/// # person.set_endpoints(Default::default());
/// use activitystreams_new::prelude::*;
///
/// assert!(person.endpoints().is_some());
/// person.delete_endpoints();
/// assert!(person.endpoints().is_none());
/// ```
fn delete_endpoints(&mut self) -> &mut Self {
self.ap_actor_mut().endpoints = None;
self
@ -197,64 +596,153 @@ pub type Organization = Object<OrganizationType>;
pub type Person = Object<PersonType>;
pub type Service = Object<ServiceType>;
/// Define activitypub properties for the Actor type as described by the Activity Pub vocabulary.
#[derive(Clone, Debug, Default, serde::Deserialize, serde::Serialize, TypedBuilder)]
#[serde(rename_all = "camelCase")]
#[builder(doc)]
pub struct ApActor<Inner> {
/// A reference to an [ActivityStreams] OrderedCollection comprised of all the messages received by the actor.
///
/// - Range: xsd:anyUri
/// - Functional: true
pub inbox: XsdAnyUri,
/// An ActivityStreams] OrderedCollection comprised of all the messages produced by the actor.
///
/// - Range: xsd:anyUri
/// - Functional: true
pub outbox: XsdAnyUri,
/// A link to an [ActivityStreams] collection of the actors that this actor is following.
///
/// - Range: xsd:anyUri
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub following: Option<XsdAnyUri>,
/// A link to an [ActivityStreams] collection of the actors that follow this actor.
///
/// - Range: xsd:anyUri
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub followers: Option<XsdAnyUri>,
/// A link to an [ActivityStreams] collection of objects this actor has liked.
///
/// - Range: xsd:anyUri
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub liked: Option<XsdAnyUri>,
/// A list of supplementary Collections which may be of interest.
///
/// - Range: xsd:anyUri
/// - Functional: false
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option, into))]
pub streams: Option<OneOrMany<XsdAnyUri>>,
/// A short username which may be used to refer to the actor, with no uniqueness guarantees.
///
/// - Range: xsd:string
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub preferred_username: Option<XsdString>,
/// A json object which maps additional (typically server/domain-wide) endpoints which may be
/// useful either for this actor or someone referencing this actor.
///
/// This mapping may be nested inside the actor document as the value or may be a link to a
/// JSON-LD document with these properties.
///
/// - Range: Endpoint
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub endpoints: Option<Endpoints>,
/// base fields and unparsed json ends up here
#[serde(flatten)]
pub inner: Inner,
}
/// A json object which maps additional (typically server/domain-wide) endpoints which may be
/// useful either for this actor or someone referencing this actor.
///
/// This mapping may be nested inside the actor document as the value or may be a link to a
/// JSON-LD document with these properties.
#[derive(Clone, Debug, Default, serde::Deserialize, serde::Serialize, TypedBuilder)]
#[serde(rename_all = "camelCase")]
pub struct Endpoints {
/// Endpoint URI so this actor's clients may access remote ActivityStreams objects which
/// require authentication to access.
///
/// To use this endpoint, the client posts an x-www-form-urlencoded id parameter with the
/// value being the id of the requested ActivityStreams object.
///
/// - Range: anyUri
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub proxy_url: Option<XsdAnyUri>,
/// If OAuth 2.0 bearer tokens [RFC6749](https://tools.ietf.org/html/rfc6749)
/// [RFC6750](https://tools.ietf.org/html/rfc6750) are being used for authenticating client to
/// server interactions, this endpoint specifies a URI at which a browser-authenticated user
/// may obtain a new authorization grant.
///
/// - Range: anyUri
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub oauth_authorization_endpoint: Option<XsdAnyUri>,
/// If OAuth 2.0 bearer tokens [RFC6749](https://tools.ietf.org/html/rfc6749)
/// [RFC6750](https://tools.ietf.org/html/rfc6750) are being used for authenticating client to
/// server interactions, this endpoint specifies a URI at which a client may acquire an access
/// token.
///
/// - Range: anyUri
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub oauth_token_endpoint: Option<XsdAnyUri>,
/// If Linked Data Signatures and HTTP Signatures are being used for authentication and
/// authorization, this endpoint specifies a URI at which browser-authenticated users may
/// authorize a client's public key for client to server interactions.
///
/// - Range: anyUri
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub provide_client_key: Option<XsdAnyUri>,
/// If Linked Data Signatures and HTTP Signatures are being used for authentication and
/// authorization, this endpoint specifies a URI at which a client key may be signed by the
/// actor's key for a time window to act on behalf of the actor in interacting with foreign
/// servers.
///
/// - Range: anyUri
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub sign_client_key: Option<XsdAnyUri>,
/// An optional endpoint used for wide delivery of publicly addressed activities and
/// activities sent to followers.
///
/// shared_inbox endpoints SHOULD also be publicly readable OrderedCollection objects
/// containing objects addressed to the Public special collection. Reading from the
/// shared_inbox endpoint MUST NOT present objects which are not addressed to the Public
/// endpoint.
///
/// - Range: anyUri
/// - Functional: true
#[serde(skip_serializing_if = "Option::is_none")]
#[builder(default, setter(strip_option))]
pub shared_inbox: Option<XsdAnyUri>,