Skip to content

Commit 6d45409

Browse files
oneirosoneiros
committed
Add documentation
1 parent eb16595 commit 6d45409

File tree

3 files changed

+152
-40
lines changed

3 files changed

+152
-40
lines changed

‎README.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,114 @@ Possible next steps:
5252
* Customize the registration process
5353
* Implement capabilities
5454

55+
## Configuration
56+
57+
The `fasp_base` engine can be configured via
58+
`config/initializers/fasp_base.rb`. The values set here will be used in
59+
the [provider info](https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications/blob/main/general/v0.1/provider_info.md)
60+
and in various other places, e.g. page titles.
61+
62+
The following can be configured:
63+
64+
* `fasp_name`: The name of your provider. Used for the provider info,
65+
page titles and name of AP actor, when data sharing is enabled
66+
* `domain`: The domain name of your provider. Used to generate URIs
67+
outside of the regular rails request/response cycle. The default in
68+
the generated configuration allows using an environment variable for
69+
this in production and uses `localhost:3000` as a fallback for other
70+
environments
71+
* `capabilities`: The list of capabilities your provider implements as
72+
returned in the provider info. Example capability:
73+
`{id: "callback", version: "0.1"}`
74+
* `privacy_policy_url`: As returned in the provider info
75+
* `privacy_policy_language`: As returned in the provider info
76+
* `contact_email`: As returned in the provider info
77+
* `fediverse_account`: As returned in the provider info
78+
79+
## User Interface
80+
81+
`fasp_base` installs an application layout and includes some basic views
82+
e.g. for user/server registration. These use TailwindCSS utility classes
83+
for styling.
84+
85+
You can decide to (re-)use this in which case you should set up your
86+
project to use TailwindCSS (v3 only for now).
87+
88+
Of course you can also add your own CSS code to style the existing
89+
views.
90+
91+
All existing views can also be overwritten in your project, so you have
92+
total conrol over markup and styling.
93+
94+
Last but not least, all controllers in `fasp_base` also try to return
95+
something sensible when a JSON content-type is request. That means that
96+
as long as you are fine with a session-cookie based authentication, you
97+
should be able to put a JS-based SPA in front of this using the
98+
framework of your choice.
99+
100+
(Note that this last use-case has not been tested, but we are happy to
101+
receive any feedback on this you might have.)
102+
103+
## Current Limitations
104+
105+
The data structure allows for a single user to have multiple servers.
106+
This is on purpose and something we want to support ASAP. But right now
107+
there is no UI to add additional servers and/or manage servers that you
108+
already have.
109+
110+
If you take the current code as-is, your provider will have an open
111+
registration, i.e. everyone can create an account and connect a server.
112+
This is probably not what most providers will want.
113+
114+
Trouble is, there are many alternatives, and we are not yet sure which
115+
make the most sense to have in such a generic base plugin.
116+
117+
Ideas include:
118+
119+
* Sign up with an invite code
120+
* Sign up with one-time invitiation URLs
121+
* Manual verification of sign ups by a (super-)admin (though this might
122+
require a spec change)
123+
124+
Feedback is very welcome.
125+
126+
## Implementing Capabilities
127+
128+
`fasp_base` requires your base URI to be at `/fasp/`. So when
129+
implementing capabilities you will probably want to define your routes
130+
under a `:fasp` namespace:
131+
132+
```ruby
133+
namespace :fasp do
134+
# ...
135+
end
136+
```
137+
138+
In your controllers you can include the `FaspBase::ApiAuthentication`
139+
module. This will automatically authenticate any requests and add a
140+
`#current_server` and `#current_user` method to access the server that
141+
was authenticated and the associated user respectively.
142+
143+
`#current_user` is also made available as a helper method to your views.
144+
145+
To make authenticated HTTP calls to a server, you can use the
146+
`FaspBase::Request` class. Create a new instance by passing a
147+
`FaspBase::Server` object:
148+
149+
```ruby
150+
request = FaspBase::Request.new(current_server)
151+
request.get("/capability/v23/test")
152+
```
153+
154+
Note that the `#get`, `#post` and `#delete` methods will automatically
155+
prepend the base URI of the server you can use path names as given in
156+
the specification of the capability.
157+
158+
For test support, have a look at the
159+
[IntegrationTestHelper](fasp_base/lib/fasp_base/integration_test_helper.rb)
160+
and
161+
[this example usage here](debug_fasp/test/integration/fasp/debug/v0/logs_test.rb).
162+
55163
## Contributing
56164

57165
See https://github.com/mastodon/.github/blob/main/CONTRIBUTING.md

‎fasp_base/README.md‎

Lines changed: 1 addition & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -2,28 +2,4 @@
22

33
A rails engine with the basics of provider-server interactions (registration, provider info, API authentication). Includes a simple server-rendered HTML frontend, but could be used headless as well.
44

5-
## Usage
6-
How to use my plugin.
7-
8-
## Installation
9-
Add this line to your application's Gemfile:
10-
11-
```ruby
12-
gem "fasp_base"
13-
```
14-
15-
And then execute:
16-
```bash
17-
$ bundle
18-
```
19-
20-
Or install it yourself as:
21-
```bash
22-
$ gem install fasp_base
23-
```
24-
25-
## Contributing
26-
Contribution directions go here.
27-
28-
## License
29-
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
5+
See the [top-level README](../README) for documentation.

‎fasp_data_sharing/README.md‎

Lines changed: 43 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,56 @@
11
# FaspDataSharing
2-
Short description and motivation.
32

4-
## Usage
5-
How to use my plugin.
3+
This rails engine includes building blocks needed to implement
4+
[FASP data sharing](https://github.com/mastodon/fediverse_auxiliary_service_provider_specifications/blob/main/discovery/data_sharing/v0.1/data_sharing.md).
65

7-
## Installation
8-
Add this line to your application's Gemfile:
6+
It is based on `fasp_base`. See [the top-level README](../README.md) for
7+
installation instructions.
8+
9+
This is not a complete solution to implement data sharing. At the very
10+
least you will still need to implement how to deal with incoming data.
11+
12+
## Creating Subscriptions
913

1014
```ruby
11-
gem "fasp_data_sharing"
12-
```
15+
FaspDataSharing::Subscription.subscribe_to_content(server, max_batch_size: 10)
16+
17+
FaspDataSharing::Subscription.subscribe_to_accounts(server, max_batch_size: 10)
1318

14-
And then execute:
15-
```bash
16-
$ bundle
19+
FaspDataSharing::Subscription.subscribe_to_trends(server, max_batch_size: 10)
1720
```
1821

19-
Or install it yourself as:
20-
```bash
21-
$ gem install fasp_data_sharing
22+
(`server` is an instance of `FaspBase::Server`.)
23+
24+
## Creating Backfill Requests
25+
26+
```ruby
27+
FaspDataSharing::BackfillRequest.make(server, category: "content")
2228
```
2329

24-
## Contributing
25-
Contribution directions go here.
30+
(Again, `server` is an instance of `FaspBase::Server`, `category` is one
31+
of `"content"`, `"account"`.
32+
33+
## Handling Incoming Notifications
34+
35+
`fasp_data_sharing` expects that you handle incoming notifications from
36+
connected fediverse servers asynchronously using `ActiveJob`.
37+
38+
To this end it defines the following jobs:
39+
40+
* `FaspDataSharing::ProcessAccountBackfillJob`
41+
* `FaspDataSharing::ProcessAccountDeletionJob`
42+
* `FaspDataSharing::ProcessAccountUpdateJob`
43+
* `FaspDataSharing::ProcessContentBackfillJob`
44+
* `FaspDataSharing::ProcessContentDeletionJob`
45+
* `FaspDataSharing::ProcessContentUpdateJob`
46+
* `FaspDataSharing::ProcessNewAccountJob`
47+
* `FaspDataSharing::ProcessNewContentJob`
48+
* `FaspDataSharing::ProcessTrendingContentJob`
49+
50+
Each job gets a single URI as its first and only parameter.
51+
52+
These classes are mostly empty. You need to overwrite them in your
53+
provider.
2654

2755
## License
2856
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

0 commit comments

Comments
 (0)