diff --git a/Cargo.toml b/Cargo.toml index 4ca27f0..cf26826 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "activitystreams" description = "Activity Streams in Rust" -version = "0.5.0-alpha.10" +version = "0.5.0-alpha.11" license = "GPL-3.0" authors = ["asonix "] repository = "https://git.asonix.dog/Aardwolf/activitystreams" diff --git a/README.md b/README.md index 7f2ded2..d651a08 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ __A set of Traits and Types that make up the ActivityStreams and ActivityPub spe First, add ActivityStreams to your dependencies ```toml -activitystreams = "0.5.0-alpha.10" +activitystreams = "0.5.0-alpha.11" ``` ### Types @@ -177,7 +177,7 @@ There are a number of features that can be disabled in this crate. By default, e enabled. ```toml -activitystreams = { version = "0.5.0-alpha.10", default-features = "false", features = ["derive"] } +activitystreams = { version = "0.5.0-alpha.11", default-features = "false", features = ["derive"] } ``` | feature | what you get | diff --git a/src/ext.rs b/src/ext.rs index 4fae96f..77c603e 100644 --- a/src/ext.rs +++ b/src/ext.rs @@ -1,4 +1,112 @@ +/* + * This file is part of ActivityStreams. + * + * Copyright © 2020 Riley Trautman + * + * ActivityStreams is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * ActivityStreams 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 General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with ActivityStreams. If not, see . + */ + //! Defining extensibility in the ActivityStreams spec +//! +//! In ActivityStreams, there are many times you may want to use an extension. For example, to +//! interact with Mastodon, you need to at least understand the `publicKey` field on their actor +//! type. If not, you won't be able to use HTTP Signatures, and will have your messages rejected. +//! +//! But this library doesn't provide any of the security extensions to ActivityStreams. In order to +//! support it, you could implment your own extensions to this library. Let's cover a basic +//! example. +//! +//! ```rust +//! // For this example, we'll use the Extensible trait, the Extension trait, the Actor trait, and +//! // the Person type +//! use activitystreams::{ +//! actor::{Actor, Person}, +//! ext::{Extensible, Extension}, +//! }; +//! +//! /// Let's define the PublicKey type. The three fields in this PublicKey struct are how Mastodon +//! /// represents Public Keys on actors. We'll need to derive Serialize and Deserialize for these +//! /// in order for them to be useful. +//! #[derive(Clone, Debug, Default, serde::Deserialize, serde::Serialize)] +//! #[serde(rename_all = "camelCase")] +//! pub struct PublicKey { +//! /// The ID of the key. +//! /// +//! /// In mastodon, this is the same as the actor's URL with a #main-key on +//! /// the end. +//! pub id: String, +//! +//! /// The ID of the actor who owns this key. +//! pub owner: String, +//! +//! /// This is a PEM file with PKCS#8 encoded data. +//! pub public_key_pem: String, +//! } +//! +//! /// Now, we'll need more than just a PublicKey struct to make this work. We'll need to define a +//! /// second struct that declares the correct key to house this information inside of +//! /// +//! /// The information is represented as the following json: +//! /// ```json +//! /// { +//! /// "publicKey": { +//! /// "id": "key id", +//! /// "owner": "actor id", +//! /// "publicKeyPem": "pem string" +//! /// } +//! /// } +//! /// ``` +//! /// +//! /// This means we'll need to define the 'publicKey' key +//! #[derive(Clone, Debug, Default, serde::Deserialize, serde::Serialize)] +//! #[serde(rename_all = "camelCase")] +//! pub struct PublicKeyExtension { +//! /// The public key's information +//! pub public_key: PublicKey +//! } +//! +//! impl PublicKey { +//! /// Let's add a convenience method to turn a PublicKey into a PublicKeyExtension +//! pub fn to_ext(self) -> PublicKeyExtension { +//! PublicKeyExtension { public_key: self } +//! } +//! } +//! +//! // And finally, we'll implement the Extension trait for PublicKeyExtension +//! // +//! // We'll bound this extension by the Actor trait, since we don't care about non-actors having +//! // keys. This means that you can put a key on a `Person`, but not on a `Video`. +//! impl Extension for PublicKeyExtension where T: Actor {} +//! +//! // Now that these types are defined, we can put them to use! +//! fn main() { +//! let person = Person::new(); +//! +//! // let's just create a dummy key for this example +//! let public_key = PublicKey { +//! id: "My ID".to_owned(), +//! owner: "Owner ID".to_owned(), +//! public_key_pem: "My Public Key".to_owned(), +//! }; +//! +//! // We're doing it! The person is being extended with a public key +//! // +//! // Note that calling `extend` on person here is possible because the Extensible trait is in +//! // scope +//! let person_with_key = person.extend(public_key.to_ext()); +//! } +//! ``` use crate::{ activity::{Activity, IntransitiveActivity}, @@ -22,6 +130,27 @@ use std::fmt::Debug; /// `Ext, AnotherType>` exists, that will implement /// `AsRef` just like the innermost `Follow`. This only works for types /// two levels deep, however. +/// +/// Usage: +/// ```rust +/// use activitystreams::object::Video; +/// +/// fn main() -> Result<(), Box> { +/// let mut video = Video::full(); +/// +/// // AsMut works even though this is an Ext +/// video +/// .as_mut() +/// .set_id("https://example.com")?; +/// +/// // set information on the extension +/// video +/// .extension +/// .set_source_xsd_any_uri("https://example.com")?; +/// +/// Ok(()) +/// } +/// ``` #[derive(Clone, Debug, Default)] #[cfg_attr(feature = "derive", derive(serde::Deserialize, serde::Serialize))] pub struct Ext { diff --git a/src/lib.rs b/src/lib.rs index 498cbd6..fcd0611 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -25,7 +25,7 @@ //! //! First, add ActivityStreams to your dependencies //! ```toml -//! activitystreams = "0.5.0-alpha.10" +//! activitystreams = "0.5.0-alpha.11" //! ``` //! //! ### Types @@ -209,7 +209,7 @@ //! enabled. //! //! ```toml -//! activitystreams = { version = "0.5.0-alpha.10", default-features = "false", features = ["derive"] } +//! activitystreams = { version = "0.5.0-alpha.11", default-features = "false", features = ["derive"] } //! ``` //! //! | feature | what you get |