]> git.r.bdr.sh - rbdr/blog/blame - doc/specs/20200601-serving-different-versions.md
Add mac
[rbdr/blog] / doc / specs / 20200601-serving-different-versions.md
CommitLineData
cce07b52
BB
1# Problem
2
3Feed reader users should be able to subscribe to the blog
4
5# Background
6
7As of this writing, the blog is served as HTML which is appropriate for
8web browsers but maybe not for other mechanisms like feed readers.
9
10Feed readers have different formats that they support:
11 * h-feed is a microformat built into the page
12 * rss and atom are XML based publishing formats
13 * JSON feed is a JSON based publishing format
14 * rss 3.0 is a text based pblishing format :P
15
16Currently the blog contains a single generator function that copies
17assets and generates HTML out of markdown files. This is good enough for
18the current setup, but if it were to generate more it would get messy
19real quick.
20
21Given the constraints listed below, some formats are not recommended:
22 * RSS 3.0 is not a good candidate at the moment as it would require
23 us to parse the markdown to extract the title.
24 * Atom would work, however, given the requirement for an id, title, and
25 date this would require more effort than a more lenient format.
26 * RSS 2.0 fits the constraints as we wouldn't need to specify anything
27 for the item.
28 * JSON Feed would work, however given the requirement for an id, thtis
29 would require more effort than a more lenient format.
30
31It is unclear whether the current constraints are good enough for feed
32readers. If this causes issues, it's likely we will have to include date,
33id or title as required in the other formats.
34
35After reviewing the functionality of existing readers, it has been found
36that an id and publication date would be needed for readers to behave
37correctly. This means that ATOM and JSON Feed would be equally valid
38as solutions than RSS 2.0
39
40The current generator function depends on knowing a source for the post
41being generated, and a target on where the assets will be placed.
42
43# Hypothesis
44
45Given we serve the blog in a feed reader friendly format, users will be able to subscribe.
46
47# Test of Hypothesis
48
49Given I add the blog to a feed reader service like Reeder or Feedly, I will be able to see the entries.
50Given I add a new entry to the blog, the entries will be updated.
51
52# Assumptions
53
54* We can generate a valid feed with just the entries themselves and the existing
55 blog data.
56 * We can: Validated by generating an example file.
57* Including just a list of items with the whole content is good enough for
58 feed readers.
59 * We can't: It seems like we'll require at least a guid. The old reader
60 behaves correctly with just the guid. It's unclear whether feedly
61 does since it has caching. Will leave grok running.
62* It isn't required to link back, and we can include the whole text.
63 * This is correct, however it might make sense to just link to the
64 blog itself.
65
66# Constraints
67
68* We won't be parsing the markdown to generate feed items.
69* We won't be adding any sort of frontmatter to the entries.
70* The blog will remain ephemeral, and we won't introduce permalinks.
71* We won't have configurable templating or options to add/remove
72 output types.
73
74# Solution Proposal
75
ae442b8f
BB
76We will add a new step in the creation process to create metadata for the
77post that will allow each post to be uniquely identified, as well as
78having a publish date related to them.
cce07b52
BB
79
80We will split the current generator function into generators, and create
81a new generator that will generate an RSS 2.0 file
82
83# Blackbox
84
85```
ae442b8f
BB
86 ╔══════════════════════╗
87 ║ When Adding a Post ║
88 ╚══════════════════════╝
89 ┌───────────────┐ ┌───────────────┐
90 │ │ │ │
91 ┌────────────────▶│ writeMetadata │─────────▶│ Metadata File │
92 │ │ │ │ │
93 │ └───────────────┘ └───────────────┘
94
95
96 │ ╔════════════════════════╗
97 │ ║ When Generating Output ║
98 │ ╚════════════════════════╝
99 │ ┌─────────────────┐ ┌───────────────┐
100 │ │ │ │ │
101 │ ┌─────▶│ StaticGenerator │───────▶│ Static Assets │
102 │ │ │ │ │ │
103 │ │ └─────────────────┘ └───────────────┘
104┌───────┐ │ ┌───────────────┐ ┌───────────┐
105│ │ │ │ │ │ │
106│ Blog │──────┼─────▶│ HTMLGenerator │─────────▶│ HTML File │
107│ │ │ │ │ │ │
108└───────┘ │ └───────────────┘ └───────────┘
109 │ ┌──────────────┐ ┌──────────┐
110 │ │ │ │ │
111 └─────▶│ RSSGenerator │──────────▶│ RSS File │
112 │ │ │ │
113 └──────────────┘ └──────────┘
cce07b52
BB
114```
115
116# Theory of Operation
117
ae442b8f
BB
118## When Adding a Post
119
120When the add function of the blog is triggered, it will shift the posts
d2dd1134 121as it currently does and then will generate a new unique ID and take the
ae442b8f
BB
122current timestamp. This will be saved in a JSON file in the output
123directory called "metadata.json"
124
125## When Generating Output
126
127When the generate function of the blog is triggered, it will iterate
128over every post. For each of them it will parse the markdown content,
129and the metadata, creating an object of type `tPost` and pushing it
130to an array.
131
132Next, it will iterate from a list of generator functions and call them
133with the source and target directories, and an array containing the `tPost`
134objects. Each generator function will do its work, throwing an exception
135if they encounter an error.
cce07b52
BB
136
137When the static generator is called, it will remove the current assets
138directory in the target directory, and recursively copy the assets from
139the source directory.
140
141When the HTML generator is called, it will parse an `html` template, using
142the posts as the context, and will place the resulting file in the target
143directory.
144
145When the RSS generator is called, it will parse an `rss` template, using
146the posts as the context, and will place the resulting file in the target
147directory.
148
149# Technical Specification
150
ae442b8f
BB
151## The Post Data Structure
152
153This spec introduces a data structure to help generate output.
154
155```
156tPost <Object>
157 +html <String> // The markup of the post
158 +publishedOn <Number> // The timestamp when this post was added
d2dd1134 159 +id <String> // The Unique ID for this post
ae442b8f
BB
160```
161
d2dd1134
BB
162Given that posts won't come in at a high enough rate, and that the
163purpouse is only to help feed readers identify each unique piece of
164content, for this version the `id` will be the same number as the
165`publishedOn`.
166
cce07b52
BB
167## The Generator Interface
168
169Every generator must implement this interface in order to work with
170Blog.
171
172* Generators MUST be a function
173* Generators SHOULD read the source, destination, and posts parameters to
174 write files.
175* Generators MUST NOT write anything into the source directory
176* Generators MUST return a promise
177* Generators SHOULD NOT resolve the promise with any information, as it will
178 be discarded
179* Generators MUST throw exceptions if they encounter an unrecoverable error
180
181```
182IGenerator(source<String>, destination<String>, posts<Array<String>>) => Promise
183```
184
185## New Generators
186
187### Static Generator
188
189This generator will have the logic to move static assets around. It will
190re-use the current asset logic in the `#_generate` method in Blog.
191
192```
193StaticGenerator <IGenerator>
194```
195
196### HTML Generator
197
198This generator will have the logic to generate an HTML file. It will
199re-use the current HTML logic in the `#_generate` method in Blog.
200
201```
202HTMLGenerator <IGenerator>
203```
204
205### RSS Generator
206
207This generator will have the logic to generate an RSS file. It will
208re-use the current HTML logic in the `#_generate` method in Blog,
209however, instead of using the `index.html` template it will use a
210`feed.xml` template that generates a valid RSS 2.0 feed document.
211
212```
213RSSGenerator <IGenerator>
214```
215
216## Modifications to existing parts of the code
217
218The `#_generate` function will be modified so it will now parse the
219post markdown, and then iterate over the generators, calling them
220so they create the appropriatet files.
221
222## Important Metrics
223
224Given we're only processing 3 blog posts, and this is a compile time
225activity and not runtime, there are no recommended metrics in terms
226of file throughput performance or runtime performance.
227
228This should change if this would ever handle a higher volume, or would
229be expected to run this process runtime.
230
231## Furhter Improvements
232
233It's recommended to eventually put more effort in assigning a unique ID
234to each post so we can use more feed formats.
235
236For more compatibility and future proofing, the same solution for
237RSS could be used to generate other feed formats, just adding
238a new generator
239
240This same solution could be extended to serve the blog in different formats
241(eg. a .txt that is easy to read in terminals)