diff --git a/Documentation/Dev Resources/index.md b/Documentation/Dev Resources/index.md index b7a465a..12d5d3f 100644 --- a/Documentation/Dev Resources/index.md +++ b/Documentation/Dev Resources/index.md @@ -1,3 +1,3 @@ # Dev Resources -This section contains tables, FAQs, and useful information for developers. +This section contains tables, FAQs, and useful information for developers. \ No newline at end of file diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Client/index.md b/Documentation/User Guide/Package Reference/ActivityPub.Client/index.md new file mode 100644 index 0000000..6d3cfc5 --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Client/index.md @@ -0,0 +1,10 @@ +# ActivityPub.Client + +This package implements logic and services necessary to implement an ActivityPub client. +[Everything is available through DI](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Client/ClientModule.cs) for simple, abstract usage. + +## Available Services + +| Service | Implementation | Description | +|-----------------------------------------------|------------------------------------------------|-----------------------------------------------------------------------------------------------| +| [`IActivityPubClient`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Client/IActivityPubClient.cs) | [`ActivityPubClient.cs`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Client/ActivityPubClient.cs) | Implements an HTTP client that automatically parses JSON-LD and constructs ActivityPub models | diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Client/toc.yml b/Documentation/User Guide/Package Reference/ActivityPub.Client/toc.yml new file mode 100644 index 0000000..b73cf38 --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Client/toc.yml @@ -0,0 +1,3 @@ +items: +- name: Overview + href: index.md \ No newline at end of file diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Common/index.md b/Documentation/User Guide/Package Reference/ActivityPub.Common/index.md new file mode 100644 index 0000000..720d059 --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Common/index.md @@ -0,0 +1,15 @@ +# ActivityPub.Common + +Contains types and logic needed by multiple ActivityPubSharp packages. +Unlike [the internal utilities](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/InternalUtils), this module is available to user code. +It is loaded implicitly by most other packages, but you can initialize it manually through [CommonModule](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Common/CommonModule.cs). +All important services and configuration classes are bound through DI. + +This module does *not* publish a package. +Instead, its included as a dependency by other packages that need it. + +## Available Options + +| Options Class | Configuration Path | Description | +|--------------------------------------------------|-----------------------|---------------------------------------------------| +| [ActivityPubOptions](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Common/Util/ActivityPubOptions.cs) | TBD - not implemented | Common, general-purpose ActivityPub configuration | \ No newline at end of file diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Common/toc.yml b/Documentation/User Guide/Package Reference/ActivityPub.Common/toc.yml new file mode 100644 index 0000000..b73cf38 --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Common/toc.yml @@ -0,0 +1,3 @@ +items: +- name: Overview + href: index.md \ No newline at end of file diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Extension.Mastodon/index.md b/Documentation/User Guide/Package Reference/ActivityPub.Extension.Mastodon/index.md new file mode 100644 index 0000000..8a90b52 --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Extension.Mastodon/index.md @@ -0,0 +1,6 @@ +# ActivityPub.Extension.Mastodon + +Implements type models and logic of Mastodon's ActivityStreams extensions. +This package is required for functional communication with ActivityPub servers. + +This package is not yet implemented. diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Extension.Mastodon/toc.yml b/Documentation/User Guide/Package Reference/ActivityPub.Extension.Mastodon/toc.yml new file mode 100644 index 0000000..b73cf38 --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Extension.Mastodon/toc.yml @@ -0,0 +1,3 @@ +items: +- name: Overview + href: index.md \ No newline at end of file diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Server.AspNetCore/index.md b/Documentation/User Guide/Package Reference/ActivityPub.Server.AspNetCore/index.md new file mode 100644 index 0000000..b90e00f --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Server.AspNetCore/index.md @@ -0,0 +1,5 @@ +# ActivityPub.Server.AspNetCore + +Implements middleware to integrate with ActivityPub through ASP.NET Core. + +This package is not yet implemented. diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Server.AspNetCore/toc.yml b/Documentation/User Guide/Package Reference/ActivityPub.Server.AspNetCore/toc.yml new file mode 100644 index 0000000..b73cf38 --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Server.AspNetCore/toc.yml @@ -0,0 +1,3 @@ +items: +- name: Overview + href: index.md \ No newline at end of file diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Server/index.md b/Documentation/User Guide/Package Reference/ActivityPub.Server/index.md new file mode 100644 index 0000000..d50d83c --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Server/index.md @@ -0,0 +1,5 @@ +# ActivityPub.Server + +Provides services to implement an ActivityPub server. + +This package is not yet implemented. diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Server/toc.yml b/Documentation/User Guide/Package Reference/ActivityPub.Server/toc.yml new file mode 100644 index 0000000..b73cf38 --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Server/toc.yml @@ -0,0 +1,3 @@ +items: +- name: Overview + href: index.md \ No newline at end of file diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Types/index.md b/Documentation/User Guide/Package Reference/ActivityPub.Types/index.md new file mode 100644 index 0000000..d638395 --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Types/index.md @@ -0,0 +1,141 @@ +# ActivityPub.Types + +Models and serialization logic for ActivityPub types. +Out-of-the-box, supports the base and extended ActivityStreams types including collections. +Supports simple JSON-LD in the compacted form. +Provides a [pre-configured serializer](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/JsonLdSerializer.cs) to convert between models and JSON. + +## Usage + +This package is loaded automatically by higher-level packages. +For standalone usage, call [`TryAddTypesModule`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/TypesModule.cs) to register all services for DI. + +## Built-in Types + +Standard ActivityStreams and ActivityPub types are modeled under the `ActivityPub.Types.AS` namespace. +Types are implemented as classes and grouped as follows: + +* [`ActivityPub.Types.AS`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS) - base types. +* [`ActivityPub.Types.AS.Collection`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/Collection) - Collection / page types. +* [`ActivityPub.Types.AS.Extended.Object`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/Extended/Object) - Extended Object types. These all derive from [`ASObject`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/ASObject.cs). +* [`ActivityPub.Types.AS.Extended.Link`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/Extended/Link) - Extended Link types. These all derive from [`ASLink`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/ASLink.cs). +* [`ActivityPub.Types.AS.Extended.Actor`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/Extended/Actor) - Extended Actor types. These all derive from [`APActor`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/APActor.cs). +* [`ActivityPub.Types.AS.Extended.Activity`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/Extended/Activity) - Extended Activity types. These all derive from [`ASActivity`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/ASActivity.cs) or one of the synthetic types described below. + +## Synthetic Types + +To improve developer experience, a few synthetic intermediate types have been introduced to the hierarchy. +These are as follows: + +* [`ASType`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/ASType.cs) - a common type between [`Link`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/ASLink.cs) and [`Object`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/ASObject.cs). This enables support for the `Range: Link | Object` construction that is common within the ActivityStreams specification. +* [`APActor`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/APActor.cs) - base type for Actor objects. Defined object types may extend this directly, and any other compatible object (includes Inbox and Outbox) will be "promoted" to include this as a standalone. + +## Entities + +### Overview + +In addition to the "model" types described above, ActivityPubSharp includes a second, lower-level type model referred to as the "entity system". +This feature can be ignored in most cases, but it is absolutely critical to use or implement an ActivityStream extension. + +### Usage + +The most common usage of the entity system can utilize a mid-level "easy path" - three special functions that are defined on all types. + +* `Is()` - returns true if the object includes a provided model, either as a base / super type or as an entirely separate type defined in the `type` property. +* `Is(out TModel? instance)` - same as before, but also constructs and returns an instance of the target model. Follows the `TryGet` pattern. +* `As()` - same as before, but returns the constructed model instead of a boolean. Throws an exception if the object doesn't contain the provided type. + +These functions should be sufficient to comfortably work with most valid ActivityPub objects, even polymorphic ones. +All related instances are automatically linked - that is, changes to one instance will be reflected in all others associated with the same object. +This is true even for base types and instances that are constructed later. + + +### Implementation + +Entities are implemented as an extra **sealed** and **non-inheriting** class associated with each type. +By convention, they are named the same as the type class with an `Entity` suffix. +For example, `ASObject` has an associated entity called `ASObjectEntity`. +Entities are typically placed in the same file as their associated type because the two are tightly coupled. +Typically, application code will not need to work with entity types directly. +However, it will be necessary if implementing a new extension or handling some rare edge cases. + +### Models vs Entities + +* Models utilize **inheritance**, while entities use **composition**. +* Entities are automatically constructed during JSON conversion, while models are lazy-constructed on-use. +* Within a single type graph, entities are singletons while models may be duplicated. +* Models represent the "expected" shape of an AS object. Entities model the "actual" runtime shape. + +### Entity Mapping + +APSharp includes a 4-step process to determine which entities should be constructed from an incoming JSON message. +All entities detected by at least one test will be converted and parsed. +1. Map values of the `type` property to registered AS type names. +2. Try all entities that implement [`INamelessEntity`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/Overrides/INamelessEntity.cs). +3. Try all entities that implement [`IAnonymousEntity`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/Overrides/IAnonymousEntity.cs). +4. Try all configured [`IAnonymousEntitySelector`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/Overrides/IAnonymousEntitySelector.cs) instances. + +## Utility Types + +These types are implemented to support certain special-case properties. +Most exist for DX only, although a few are needed for type-model accuracy or serialization purposes. + +* [`ASUri`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Util/ASUri.cs) - (will) implement the namespaced IRI concept used in JSON-LD. For now, just a wrapper around `Uri`. +* [`JsonLDContext`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Util/JsonLDContext.cs) - provides a consolidated view of the JSON-LD context associated with an object. +* [`JsonLDContextObject`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Util/JsonLDContextObject.cs) - encapsulates the `object | IRI` typing used in the JSON-LD context. Does not parse or enforce IRI correctness - its just a `string`. +* [`JsonLDTerm`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Util/JsonLDTerm.cs) - encapsulates the `object | IRI` typing used in JSON-LD term definitions. Does not parse or enforce IRI correctness - its just a `string`. +* [`Linkable`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Util/Linkable.cs) - encapsulates the `Range: Link | T` construction used in ActivityStreams. +* [`LinkableList`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Util/LinkableList.cs) - encapsulates the `Range: (Link | T)[]` construction used in ActivityStreams, as well as the extra cursed `Link | T | (Link | T)[]` variant. +* [`NaturalLanguageString`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Util/NaturalLanguageString.cs) - models BCP47 language-tag mapped strings. + +## Collections + +ActivityStreams Collection types are implemented in the [`ActivityPub.Types.AS.Collection` namespace](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/Collection). +All four basic types are modeled, and the implementations support extensions like any other type. + +Collections are, currently, a weak point in the library. +They are fully implemented and functional, but the API is not particularly ergonomic. +One notable limitation is that ordered and unordered collections do not have a common base type, which makes it difficult to implement code that handles either form. +Another limitation is `TotalItems` - if unset, it returns the size of `Items`. +But once set to any value, it cannot be reset to null and therefore the original logic is unavailable. +These limitations will be resolved at a later date. + +## Extensibility + +### Overview + +ActivityPubSharp includes support for most valid ActivityStreams extensions. +Custom types are supported, and extensions of built-in types can be emulated by inheriting from the original type. +JSON-LD contexts are followed while constructing extension types, although property names are not currently remapped. + +### Usage + +At startup, the module scans all loaded assemblies and registers any type deriving from [ASType](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/AS/ASType.cs) and implementing [IASModel](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/IASModel.cs). +Registered extension classes will be automatically constructed by the [polymorphic converter](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/Converters/TypeMapConverter.cs). +Polymorphic extension types will be handled by the Entities system described above. + +Extensions types should include a link to the context that defines them. +If the extension in question is not properly defined (has no context), then it can be excluded. +However, extension classes without a defined context will instead be placed into the ActivityStreams context, which will apply them to +**all** objects. + +See the [ActivityStreams documentation](https://www.w3.org/TR/activitystreams-core/#extensibility) for more information on extensibility. + +## Limitations + +* Several properties and edge cases are not correctly handled. See the [issue tracker](https://github.com/warriordog/ActivityPubSharp/issues) for details. +* Only a minimal subset of JSON-LD is supported. For full compatibility, it is necessary to override the default [JsonLdSerializer](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/JsonLdSerializer.cs) and pre-process the incoming JSON. + +## Available Options + +| Options Class | Configuration Path | Description | +|------------------------------------------------------------------|-----------------------------|----------------------------------------------------------------------------| +| [JsonLdSerializerOptions](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/JsonLdSerializerOptions.cs) | N/A - not mapped by default | Options for the default [JsonLdSerializer](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/JsonLdSerializer.cs) | +| [ConversionOptions](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/Overrides/ConversionOptions.cs) | N/A - not mapped by default | General JSON / JSON-LD conversion options | + +## Available Services + +| Service | Implementation | Description | +|-------------------------------------------------------|---------------------------------------------------------|-----------------------------------------------------------------------| +| [`IJsonLdSerializer`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/JsonLdSerializer.cs) | [`JsonLdSerializer.cs`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/JsonLdSerializer.cs) | Parses and serializes ActivityStreams messages from JSON or JSON-LD. | +| [`IASTypeInfoCache`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/ASTypeInfoCache.cs) | [`ASTypeInfoCache`](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/ASTypeInfoCache.cs) | Indexes metadata related to AS / AP types defined in the application. | diff --git a/Documentation/User Guide/Package Reference/ActivityPub.Types/toc.yml b/Documentation/User Guide/Package Reference/ActivityPub.Types/toc.yml new file mode 100644 index 0000000..b73cf38 --- /dev/null +++ b/Documentation/User Guide/Package Reference/ActivityPub.Types/toc.yml @@ -0,0 +1,3 @@ +items: +- name: Overview + href: index.md \ No newline at end of file diff --git a/Documentation/User Guide/Package Reference/index.md b/Documentation/User Guide/Package Reference/index.md new file mode 100644 index 0000000..d02d322 --- /dev/null +++ b/Documentation/User Guide/Package Reference/index.md @@ -0,0 +1,62 @@ +# Packaeg Reference + +## About +ActivityPubSharp is a toolkit of modular packages that support the use of ActivityPub in .NET applications. +Low-level APIs offer raw - but safe - access to strongly-typed models, while high-level interfaces support ergonomic and standards-compliant use of the protocol. +Special utility types and integrated JSON-LD converters further abstract ActivityPub's rougher edges, bringing the user experience up to par with more traditional APIs. +For more information, see the introduction post - [*What is ActivityPubSharp?*](https://github.com/warriordog/ActivityPubSharp/discussions/63) + +### Modularity +Modularity and Abstraction are keys goals of this project. +It should be simple to integrate this library at any appropriate level of abstraction. +Low-level apps can utilize the [strongly-typed models](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types) and utility types, but bring their own parser, logic, and other components. +Mid-level apps may want to use the [HTTP client](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Client) or [abstract server logic](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Server). +On the other hand, high-level apps will likely desire framework integration and custom middleware. + +To support these varying use cases, ActivityPubSharp is split into multiple separate NuGet packages. +While separate and self-contained, these packages are designed to work together and will seamlessly integrate through Dependency Injection. +A typical use case will include the highest-level "main" package needed for the application, and then as many "secondary" packages as desired for extra functionality. + +| Package | Links | Description | Use Case | +|--------------------------------|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| +| ActivityPub.Types | [NuGet](https://www.nuget.org/packages/ActivityPub.Types), [Source](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types) | Serializable type definitions for ActivityPub types. Includes utility classes to handle polymorphic properties. | You only need the ActivityPub object types, and nothing else. | +| ActivityPub.Common | [NuGet](https://www.nuget.org/packages/ActivityPub.Common), [Source](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Common) | Core utilities, services, and configuration for all ActivityPub use cases. | You are using any other part of this library. | +| ActivityPub.Client | [NuGet](https://www.nuget.org/packages/ActivityPub.Client), [Source](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Client) | Implementation of the Client conformance class. Supports the client side of [Client to Server interactions](https://www.w3.org/TR/activitypub/#client-to-server-interactions). | You are implementing the Client conformance class. | +| ActivityPub.Server | [NuGet](https://www.nuget.org/packages/ActivityPub.Server), [Source](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Server) | Implementation of the Server conformance class. Supports the server side of [Client to Server interactions](https://www.w3.org/TR/activitypub/#client-to-server-interactions). | You are implementing the Server conformance class, with or without Federation. | +| ActivityPub.Server.AspNetCore | [NuGet](https://www.nuget.org/packages/ActivityPub.Server.AspNetCore), [Source](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Server.AspNetCore) | Extends Server package with bindings and middleware for ASP.NET Core. | You are implementing a server that will utilize ASP.NET. | +| ActivityPub.Extension.Mastodon | [NuGet](https://www.nuget.org/packages/ActivityPub.Extension.Mastodon), [Source](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Extension.Mastodon) | Extended type definitions and logic for integration with Mastodon. | You are communicating with a Mastodon server. | + +### Non-goals +As the name suggests, ActivityPubSharp is focused specifically on ActivityPub rather than ActivityStreams, JSON-LD, or any other relational data standard. +While ActivityStreams *is* implemented as an underlying component of ActivityPub, it cannot be used standalone with this library. +The same is true of JSON-LD. +If there is ever a conflict between specifications, then the [ActivityPub spec](https://www.w3.org/TR/activitypub/) spec will be considered authoritative. + +At present, ActivityPubSharp intends to offer only a subset of JSON-LD support. +The included serializers support all features that are necessary for ActivityPub and integration with mainstream fediverse software, but that is all. +Attempting to parse other forms of linked data may fail catastrophically. +In the future, it will be possible to inject a user-provided compaction/normalization layer through DI. +Advanced applications can use this feature to support JSON-LD while still using ActivityPubSharp's high-level APIs. + +### Customization +ActivityPubSharp utilizes Dependency Injection to customize and extend the library. +For example, included services all utilize the [`IJsonLdSerializer` interface](https://github.com/warriordog/ActivityPubSharp/blob/main/Source/ActivityPub.Types/Conversion/JsonLdSerializer.cs) which enables user code to replace or modify the default JSON support. +Most default implementations expose configuration objects that are compatible with the Options Pattern. +User-accessible DI services and and options are described in the README for each individual package. + +## Getting Started + +ActivityPubSharp is not yet production-ready. +Most high-level functionality is not implemented. +There is, however, [an example package](https://github.com/warriordog/ActivityPubSharp/blob/main/Example) available with reference code. + +## Technical Details + +### Requirements +* .NET 7 (newer should work, but is untested) +* Any supported platform - no native code is used + +### Design Goals +* Minimal dependencies - software supply chain risks are an underappreciated threat. ActivityPubSharp keeps minimal dependencies to reduce the supply chain footprint. +* Modern .NET - ActivityPubSharp has set .NET 7 as the minimum supported version. This unfortunately excludes some projects, but is critical for System.Text.Json support. +* Ergonomic and Conventional APIs - mid/high level APIs should feel and function like typical .NET APIs. An important goal (and difficult challenge) of this project is abstracting ActivityPub's dynamic nature to better fit with C#'s strongly-typed model. \ No newline at end of file diff --git a/Documentation/User Guide/Package Reference/toc.yml b/Documentation/User Guide/Package Reference/toc.yml new file mode 100644 index 0000000..57a13b7 --- /dev/null +++ b/Documentation/User Guide/Package Reference/toc.yml @@ -0,0 +1,12 @@ +- name: ActivityPub Client Package + href: ActivityPub.Client/index.md +- name: ActivityPub Common Library + href: ActivityPub.Common/index.md +- name: ActivityPub Server Package + href: ActivityPub.Server/index.md +- name: ActivityPub Server AspNetCore Extension Package + href: ActivityPub.Server.AspNetCore/index.md +- name: ActivityPub Types Package + href: ActivityPub.Types/index.md +- name: ActivityPub Mastodon Extension Package + href: ActivityPub.Extension.Mastodon/index.md \ No newline at end of file diff --git a/Documentation/User Guide/toc.yml b/Documentation/User Guide/toc.yml index 36270ab..d2ef25f 100644 --- a/Documentation/User Guide/toc.yml +++ b/Documentation/User Guide/toc.yml @@ -2,4 +2,6 @@ - name: User Guide href: index.md - name: Getting Started - href: getting_started.md \ No newline at end of file + href: getting_started.md +- name: Package Reference + href: Package%20Reference/ \ No newline at end of file diff --git a/Source/ActivityPub.Client/readme.md b/Source/ActivityPub.Client/readme.md index 7de9dd0..a2c98c7 100644 --- a/Source/ActivityPub.Client/readme.md +++ b/Source/ActivityPub.Client/readme.md @@ -3,8 +3,4 @@ This package implements logic and services necessary to implement an ActivityPub client. [Everything is available through DI](ClientModule.cs) for simple, abstract usage. -## Available Services - -| Service | Implementation | Description | -|-----------------------------------------------|------------------------------------------------|-----------------------------------------------------------------------------------------------| -| [`IActivityPubClient`](IActivityPubClient.cs) | [`ActivityPubClient.cs`](ActivityPubClient.cs) | Implements an HTTP client that automatically parses JSON-LD and constructs ActivityPub models | +[Package Reference](https://warriordog.github.io/ActivityPubSharp/User%20Guide/Package%20Reference/ActivityPub.Client) \ No newline at end of file diff --git a/Source/ActivityPub.Common/readme.md b/Source/ActivityPub.Common/readme.md index c17e036..6315c7a 100644 --- a/Source/ActivityPub.Common/readme.md +++ b/Source/ActivityPub.Common/readme.md @@ -8,8 +8,4 @@ All important services and configuration classes are bound through DI. This module does *not* publish a package. Instead, its included as a dependency by other packages that need it. -## Available Options - -| Options Class | Configuration Path | Description | -|--------------------------------------------------|-----------------------|---------------------------------------------------| -| [ActivityPubOptions](Util/ActivityPubOptions.cs) | TBD - not implemented | Common, general-purpose ActivityPub configuration | +[Package Reference](https://warriordog.github.io/ActivityPubSharp/User%20Guide/Package%20Reference/ActivityPub.Common) diff --git a/Source/ActivityPub.Extension.Mastodon/readme.md b/Source/ActivityPub.Extension.Mastodon/readme.md index 8a90b52..720ec2e 100644 --- a/Source/ActivityPub.Extension.Mastodon/readme.md +++ b/Source/ActivityPub.Extension.Mastodon/readme.md @@ -4,3 +4,5 @@ Implements type models and logic of Mastodon's ActivityStreams extensions. This package is required for functional communication with ActivityPub servers. This package is not yet implemented. + +[Package Reference](https://warriordog.github.io/ActivityPubSharp/User%20Guide/Package%20Reference/ActivityPub.Extension.Mastodon) \ No newline at end of file diff --git a/Source/ActivityPub.Server.AspNetCore/readme.md b/Source/ActivityPub.Server.AspNetCore/readme.md index 5aff5bf..d2adf73 100644 --- a/Source/ActivityPub.Server.AspNetCore/readme.md +++ b/Source/ActivityPub.Server.AspNetCore/readme.md @@ -2,4 +2,6 @@ Implements middleware to integrate with ActivityPub through ASP.NET Core. -This package is not yet implement. \ No newline at end of file +This package is not yet implement. + +[Package Reference](https://warriordog.github.io/ActivityPubSharp/User%20Guide/Package%20Reference/ActivityPub.Server.AspNetCore) \ No newline at end of file diff --git a/Source/ActivityPub.Server/readme.md b/Source/ActivityPub.Server/readme.md index c7956f7..3694cb2 100644 --- a/Source/ActivityPub.Server/readme.md +++ b/Source/ActivityPub.Server/readme.md @@ -1,4 +1,6 @@ # ActivityPub.Server Provides services to implement an ActivityPub server. -Not yet implemented. \ No newline at end of file +Not yet implemented. + +[Package Reference](https://warriordog.github.io/ActivityPubSharp/User%20Guide/Package%20Reference/ActivityPub.Server) \ No newline at end of file diff --git a/Source/ActivityPub.Types/readme.md b/Source/ActivityPub.Types/readme.md index e40b196..4219924 100644 --- a/Source/ActivityPub.Types/readme.md +++ b/Source/ActivityPub.Types/readme.md @@ -5,133 +5,4 @@ Out-of-the-box, supports the base and extended ActivityStreams types including c Supports simple JSON-LD in the compacted form. Provides a [pre-configured serializer](Conversion/JsonLdSerializer.cs) to convert between models and JSON. -## Usage - -This package is loaded automatically by higher-level packages. -For standalone usage, call [`TryAddTypesModule`](TypesModule.cs) to register all services for DI. - -## Built-in Types - -Standard ActivityStreams and ActivityPub types are modeled under the `ActivityPub.Types.AS` namespace. -Types are implemented as classes and grouped as follows: - -* [`ActivityPub.Types.AS`](AS) - base types. -* [`ActivityPub.Types.AS.Collection`](AS/Collection) - Collection / page types. -* [`ActivityPub.Types.AS.Extended.Object`](AS/Extended/Object) - Extended Object types. These all derive from [`ASObject`](AS/ASObject.cs). -* [`ActivityPub.Types.AS.Extended.Link`](AS/Extended/Link) - Extended Link types. These all derive from [`ASLink`](AS/ASLink.cs). -* [`ActivityPub.Types.AS.Extended.Actor`](AS/Extended/Actor) - Extended Actor types. These all derive from [`APActor`](AS/APActor.cs). -* [`ActivityPub.Types.AS.Extended.Activity`](AS/Extended/Activity) - Extended Activity types. These all derive from [`ASActivity`](AS/ASActivity.cs) or one of the synthetic types described below. - -## Synthetic Types - -To improve developer experience, a few synthetic intermediate types have been introduced to the hierarchy. -These are as follows: - -* [`ASType`](AS/ASType.cs) - a common type between [`Link`](AS/ASLink.cs) and [`Object`](AS/ASObject.cs). This enables support for the `Range: Link | Object` construction that is common within the ActivityStreams specification. -* [`APActor`](AS/APActor.cs) - base type for Actor objects. Defined object types may extend this directly, and any other compatible object (includes Inbox and Outbox) will be "promoted" to include this as a standalone. - -## Entities - -### Overview - -In addition to the "model" types described above, ActivityPubSharp includes a second, lower-level type model referred to as the "entity system". -This feature can be ignored in most cases, but it is absolutely critical to use or implement an ActivityStream extension. - -### Usage - -The most common usage of the entity system can utilize a mid-level "easy path" - three special functions that are defined on all types. - -* `Is()` - returns true if the object includes a provided model, either as a base / super type or as an entirely separate type defined in the `type` property. -* `Is(out TModel? instance)` - same as before, but also constructs and returns an instance of the target model. Follows the `TryGet` pattern. -* `As()` - same as before, but returns the constructed model instead of a boolean. Throws an exception if the object doesn't contain the provided type. - -These functions should be sufficient to comfortably work with most valid ActivityPub objects, even polymorphic ones. -All related instances are automatically linked - that is, changes to one instance will be reflected in all others associated with the same object. -This is true even for base types and instances that are constructed later. - - -### Implementation - -Entities are implemented as an extra **sealed** and **non-inheriting** class associated with each type. -By convention, they are named the same as the type class with an `Entity` suffix. -For example, `ASObject` has an associated entity called `ASObjectEntity`. -Entities are typically placed in the same file as their associated type because the two are tightly coupled. -Typically, application code will not need to work with entity types directly. -However, it will be necessary if implementing a new extension or handling some rare edge cases. - -### Models vs Entities - -* Models utilize **inheritance**, while entities use **composition**. -* Entities are automatically constructed during JSON conversion, while models are lazy-constructed on-use. -* Within a single type graph, entities are singletons while models may be duplicated. -* Models represent the "expected" shape of an AS object. Entities model the "actual" runtime shape. - -### Entity Mapping - -By default, APSharp checks the `@context` and `type` properties to determine whether an object can be projected to a given model or entity. -Entities without a type will be converted purely based on the context. -This logic can be altered by overriding `IASModel.ShouldConvertFrom` and performing additional checks. - -## Utility Types - -These types are implemented to support certain special-case properties. -Most exist for DX only, although a few are needed for type-model accuracy or serialization purposes. - -* [`ASUri`](Util/ASUri.cs) - (will) implement the namespaced IRI concept used in JSON-LD. For now, just a wrapper around `Uri`. -* [`JsonLDContext`](Util/JsonLDContext.cs) - provides a consolidated view of the JSON-LD context associated with an object. -* [`JsonLDContextObject`](Util/JsonLDContextObject.cs) - encapsulates the `object | IRI` typing used in the JSON-LD context. Does not parse or enforce IRI correctness - its just a `string`. -* [`JsonLDTerm`](Util/JsonLDTerm.cs) - encapsulates the `object | IRI` typing used in JSON-LD term definitions. Does not parse or enforce IRI correctness - its just a `string`. -* [`Linkable`](Util/Linkable.cs) - encapsulates the `Range: Link | T` construction used in ActivityStreams. -* [`LinkableList`](Util/LinkableList.cs) - encapsulates the `Range: (Link | T)[]` construction used in ActivityStreams, as well as the extra cursed `Link | T | (Link | T)[]` variant. -* [`NaturalLanguageString`](Util/NaturalLanguageString.cs) - models BCP47 language-tag mapped strings. - -## Collections - -ActivityStreams Collection types are implemented in the [`ActivityPub.Types.AS.Collection` namespace](AS/Collection). -All four basic types are modeled, and the implementations support extensions like any other type. - -Collections are, currently, a weak point in the library. -They are fully implemented and functional, but the API is not particularly ergonomic. -One notable limitation is that ordered and unordered collections do not have a common base type, which makes it difficult to implement code that handles either form. -Another limitation is `TotalItems` - if unset, it returns the size of `Items`. -But once set to any value, it cannot be reset to null and therefore the original logic is unavailable. -These limitations will be resolved at a later date. - -## Extensibility - -### Overview - -ActivityPubSharp includes support for most valid ActivityStreams extensions. -Custom types are supported, and extensions of built-in types can be emulated by inheriting from the original type. -JSON-LD contexts are followed while constructing extension types, although property names are not currently remapped. - -### Usage - -At startup, the module scans all loaded assemblies and registers any type deriving from [ASType](AS/ASType.cs) and implementing [IASModel](IASModel.cs). -Registered extension classes will be automatically constructed by the [polymorphic converter](Conversion/Converters/TypeMapConverter.cs). -Polymorphic extension types will be handled by the Entities system described above. - -Extensions types should include a link to the context that defines them. -If the extension in question is not properly defined (has no context), then it can be excluded. -However, extension classes without a defined context will instead be placed into the ActivityStreams context, which will apply them to -**all** objects. - -See the [ActivityStreams documentation](https://www.w3.org/TR/activitystreams-core/#extensibility) for more information on extensibility. - -## Limitations - -* Several properties and edge cases are not correctly handled. See the [issue tracker](https://github.com/warriordog/ActivityPubSharp/issues) for details. -* Only a minimal subset of JSON-LD is supported. For full compatibility, it is necessary to override the default [JsonLdSerializer](Conversion/JsonLdSerializer.cs) and pre-process the incoming JSON. - -## Available Options - -| Options Class | Configuration Path | Description | -|------------------------------------------------------------------|-----------------------------|----------------------------------------------------------------------------| -| [JsonLdSerializerOptions](Conversion/JsonLdSerializerOptions.cs) | N/A - not mapped by default | Options for the default [JsonLdSerializer](Conversion/JsonLdSerializer.cs) | -| [ConversionOptions](Conversion/Overrides/ConversionOptions.cs) | N/A - not mapped by default | General JSON / JSON-LD conversion options | - -## Available Services - -| Service | Implementation | Description | -|-------------------------------------------------------|---------------------------------------------------------|-----------------------------------------------------------------------| -| [`IJsonLdSerializer`](Conversion/JsonLdSerializer.cs) | [`JsonLdSerializer.cs`](Conversion/JsonLdSerializer.cs) | Parses and serializes ActivityStreams messages from JSON or JSON-LD. | +[Package Reference](https://warriordog.github.io/ActivityPubSharp/User%20Guide/Package%20Reference/ActivityPub.Types) \ No newline at end of file