More high-level admin documentation

[courajs]

• What are sessions? What do I use them for?
• What are admin requests?
• What are tokens?
• What are roles?

[ransomw]

i suppose these things aren't as well documented by hoodie for two reasons:

• they're under development (so subject to change)
• they're common themes across web apps.

django, for example, has excellent documentation of sessions, admin actions, and groups (analogous to roles).

a little more documentation could definitely be helpful, however, as hoodie is a little different than libraries for the server-side. an easy way to get started on such documentation might be in the form of brief descriptions, links to other projects, and then descriptions of the difference (or possibly "the hoodie difference ™/∇") between these terms as they're used in other libraries and what they mean wrt. hoodie.

[gr2m]

Sorry this is all in the flux, better documentation is lucking, but let me give this a spin.

What are sessions? What do I use them for?

For now, hoodieAdmin.sessions only support the add method, because CouchDB keeps no state of sessions, so things like hoodieAdmin.sessions.findAll() or hoodieAdmin.sessions.on("remove", handler) cannot be implemented at this time.

hoodieAdmin.sessions.add({username: 'courajs'}) allows us is to generate a valid session for user "'courajs'", helpful for debugging issues with your app for example.

Requests

This definitely need some explanation. Requests is a simple way to extend the hoodie-account-server’s logic. A request is for example "passwordreset", another request could be "upgrade", which would require e.g. a stripe token and if successful it would update the user’s account to a new plan.

You can pass a requests option to the hoodie-account-server hapi plugin. Requests are also not yet persisted, but will be in future.

Tokens

Tokens allow a user to sign in / authenticate once. For example, instead of sending a new password in an email as response to a password reset request, we should send a token. We would store this token in the user account and remove it once it has been used.

Roles

Roles can be used for things like user groups, sharing data, etc. Roles directly map to CouchDB’s roles, they can be used to give a user read/write access to a database.

For example, we want to implement user groups in the future, probably as a plugin. The plugin would listen for a new signup, store the company of the user in a separate database like groups, then take the document id (say it’s groupid123) and create a new database "group/groupid123". Then we would add a role group/groupid123 to the users account and start replicating between the user’s database and the group’s database. The user could then add more user accounts for their colleagues, and each user would get the same role and also a replication to the group database, so all users from the same group can collaborate on their groups data.

[courajs]

Awesome! Chatting with @gr2m I also asked how you use the sessions generated by sessions.add(). Essentially it's a low-level primitive, so that isn't really determined yet. You could perhaps write a function to place the sessionId into localStorage, "taking over" that session. Or you could perhaps use it to create a valid session in another browser to have your admin & user-specific sessions at the same time.

[gr2m]

to have your admin & user-specific sessions at the same time

as a side note, we do not use cookies but send session ids in request headers, so you can have several sessions at the same time in the same browser. For example you can be signed in as an admin and as a user, which is why we can put the admin dashboard at /hoodie/admin on the same domain, without interfering with an existing user session

[courajs]

Good to know 😁