1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
---
title: joyce - record your thoughts as they come
author: Federico Igne
date: \today
---
`joyce` is an attempt at building a tool for rapid notetaking, i.e., quick collection of short thoughts that can come to mind at any point.
On a high-level, this system should be:
- *Hubiquitous*, needs to be available (read/write) whenever one has internet connection (falling back to pen&paper, otherwise).
- *Searchable*, one has to be able to search and filter the pile of notes.
- *Out of the way*, sophistication will only get in the way of recording one's thoughts.
`joyce` is structured as a small tool written in Rust running on a server, loosely inspired by [`twtxt`](https://github.com/buckket/twtxt).
Clients interface themselves with the server through a simple REST API.
# Notes
Notes are the first-class citizen of `joyce` and are the main content exchanged between server and clients.
Notes, along with their REST API are defined in their own module
```{#main_mods .rust}
mod note;
```
```{#note.rs .rust path="src/"}
<<note_uses>>
<<note_struct>>
<<note_impl>>
<<req_get_notes>>
```
## Anatomy of a note
A *note* is a simple structure recording a timestamp determined at creation, a list of tags, and the body of the note.
```{#note_struct .rust}
#[derive(Debug, Deserialize, Serialize)]
pub struct Note {
timestamp: DateTime<Utc>,
tags: Vec<String>,
body: String,
}
<<note_collection>>
```
```{#note_impl .rust}
impl Note {
fn new(body: String, tags: Vec<String>) -> Self {
Self { timestamp: Utc::now(), tags, body }
}
}
```
A set of notes is just a `Vec` of `Note`s.
```{#note_collection .rust}
type Notes = Vec<Note>;
```
### (De)serialization
Since notes need to be sent and received via HTTP, the structure needs to be *serializable*.
```{#dependencies .toml}
serde = { version = "1.0", features = ["derive"] }
```
```{#note_uses .rust}
use serde::{Serialize, Deserialize};
```
### Timestamps
Timestamps adhere the *RFC 3339 date-time standard* with UTC offset.
```{#dependencies .toml}
chrono = { version = "0.4", features = ["serde"] }
```
```{#note_uses .rust}
use chrono::prelude::{DateTime, Utc};
```
# The REST API
`joyce` uses [`actix-web`](https://actix.rs/) to handle HTTP requests and responses.
```{#dependencies .toml}
actix-web = "4.1"
```
## Resources
- [Tutorial](https://web.archive.org/web/20220710213947/https://hub.qovery.com/guides/tutorial/create-a-blazingly-fast-api-in-rust-part-1/)
- [Introduction to `actix`](https://actix.rs/docs/getting-started/)
## GET /notes
Each request handlers is an *async* function that accepts zero or more parameters, extracted from a request (see [`FromRequest`](https://docs.rs/actix-web/latest/actix_web/trait.FromRequest.html) trait), and returns an [`HttpResponse`](https://docs.rs/actix-web/latest/actix_web/struct.HttpResponse.html).
Here we are requesting the list of notes currently in the system.
The function takes 0 parameters and returns a JSON object.
```{#note_uses .rust}
use actix_web::{HttpResponse,get};
use actix_web::http::header::ContentType;
```
```{#req_get_notes .rust}
#[get("/notes")]
pub async fn list() -> HttpResponse {
let mut notes: Notes = vec![];
<<notes_retrieve>>
HttpResponse::Ok()
.content_type(ContentType::json())
.json(notes)
}
```
# The program
The main program is structured as follows
```{#main.rs .rust path="src/"}
<<main_uses>>
<<main_mods>>
<<main_service>>
```
# Main service
The main service will instantiate a new `App` running within a `HttpServer` bound to *localhost* on port 8080.
```{#main_uses .rust}
use actix_web::{App, HttpServer};
```
The `App` will register all request handlers defined above.
```{#main_service .rust}
#[actix_web::main]
async fn main() -> std::io::Result<()> {
HttpServer::new(|| {
App::new()
.service(note::list)
})
.bind(("127.0.0.1", 8080))?
.run()
.await
}
```
# Testing
```{#notes_retrieve .rust}
notes.push(Note::new(
String::from("This is a first test note!"),
vec![String::from("test"), String::from("alpha"), String::from("literate")]));
notes.push(Note::new(
String::from("This is my favourite emoji: 🦥"),
vec![String::from("test"), String::from("emoji")]));
notes.push(Note::new(
String::from("Here is a link: https://www.federicoigne.com/"),
vec![String::from("test"), String::from("links")]));
```
# Open questions
- Should one be able to delete notes? Or mark them as read/processed?
- Authentication method?
- Custom filters on retrieval.
# Credits
`joyce v0.1.0` was created by Federico Igne ([git@federicoigne.com](mailto:git@federicoigne.com)) and available at [`https://git.dyamon.me/projects/joyce`](https://git.dyamon.me/projects/joyce).
```{#Cargo.toml .toml}
[package]
name = "joyce"
version = "0.1.0"
edition = "2021"
[dependencies]
<<dependencies>>
```
|
