% % Copyright (c) 2024 Andrea Biscuola % % Permission to use, copy, modify, and distribute this software for any % purpose with or without fee is hereby granted, provided that the above % copyright notice and this permission notice appear in all copies. % % THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES % WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF % MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR % ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES % WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. % -module(dudeswave_user_handler). -moduledoc """ JSON API to manage users. The username should be passed as the last token in the request, like: ``` /user/foo ``` Where `foo` is the actual username. The user parameter must be called `username` as this module expects it in order to work properly. All the requests must be done with a valid session cookie in order to work. If the session is not valid, all the requests will return `403 Forbidden` to the client. In case a technical problem occurs, `500 Internal Server Error` is returned. This module accepts four methods: - GET /user/:username Retrieve user's details. However, this call requires the user to have a valid cookie set. Not suitable for a public page. - POST /user/:username Update user's details, like their name, description and whatnot. - DELETE /user/:username Remove a user forever. The data is delete immediately. However, it's content is left up there. Probably a specific option will be added later. This request does not have a body. The call deletes the user immediately, however we return `202 Accepted` in case of success, for the simple reason that we may make the call asynchronous to remove additional content in background. - PUT /user/:username Register a user. The registration takes only three parameter: username, password and e-mail. The e-mail is required if a confirmation message is to be sent. The plan is to have a separate process handle this, so the API just need to set the proper value for the user's `status` in it's metadata. JSON APIs GET /user/:username ``` { "user" : "foo", "email": "foo@example.com", "description": "A wonderful user", "name": "Fantastic Foo" } ``` Response codes: - 200 OK (Success) - 404 Not Found PUT /user/:username ``` { "email": "foo@example.com", "password": "123456" } ``` Response codes: - 201 Created - 400 Bad Request - 409 Conflict (User already exists) POST /user/:username ``` { "email": "foo@example.com", "description": "A wonderful user", "name": "Fantastic Foo" } ``` Response codes: - 200 OK - 400 Bad Request - 404 Not Found DELETE /user/:username - 202 Accepted - 404 Not Found """. -behaviour(cowboy_handler). -export([init/2, terminate/3]). % % Callbacks exports % -export([allowed_methods/2, content_types_provided/2, content_types_accepted/2, known_methods/2, is_authorized/2, forbidden/2, resource_exists/2, is_conflict/2, previously_existed/2, allow_missing_post/2, delete_resource/2, create_user/2, modify_user/2, delete_completed/2, user_details/2]). % % Cowboy standard callbacks % init(Req, State) -> {cowboy_rest, Req, State}. known_methods(Req, State) -> {[<<"POST">>, <<"PUT">>, <<"DELETE">>, <<"GET">>], Req, State}. allowed_methods(Req, State) -> {[<<"POST">>, <<"PUT">>, <<"DELETE">>, <<"GET">>], Req, State}. is_authorized(Req, State) -> {true, Req, State}. forbidden(Req, State) -> case cowboy_req:method(Req) of <<"PUT">> -> {false, Req, State}; _ -> #{dudeauth := Auth} = cowboy_req:match_cookies([dudeauth], Req), {ok, Bucket} = maps:find(cookies, State), User = cowboy_req:binding(username, Req), case dudeswave_auth:authenticate({cookie, User, Auth}, Bucket) of {error, service_unavailable} -> exit(service_unavailable); true -> {false, Req, State}; false -> {true, Req, State} end end. content_types_provided(Req, State) -> case cowboy_req:method(Req) of <<"PUT">> -> {[{<<"application/json">>, create_user}], Req, State}; <<"POST">> -> {[{<<"application/json">>, modify_user}], Req, State}; <<"DELETE">> -> {[{<<"application/json">>, delete_user}], Req, State}; <<"GET">> -> {[{<<"application/json">>, user_details}], Req, State} end. content_types_accepted(Req, State) -> case cowboy_req:method(Req) of <<"PUT">> -> {[{<<"application/json">>, create_user}], Req, State}; <<"POST">> -> {[{<<"application/json">>, modify_user}], Req, State} end. resource_exists(Req, State) -> User = cowboy_req:binding(username, Req), {ok, Bucket} = maps:find(bucket, State), case dudeswave_auth:user_details(User, Bucket) of [] -> {false, Req, State}; {error, Reason} -> exit(Reason); Details -> NewState = State#{ bucket => Bucket, details => Details, user_exists => true, request => cowboy_req:method(Req) }, {true, Req, NewState} end. previously_existed(Req, State) -> {false, Req, State}. is_conflict(Req, #{user_exists := true, request := <<"PUT">>}) -> {true, Req, []}; is_conflict(Req, State) -> {false, Req, State}. allow_missing_post(Req, State) -> {false, Req, State}. delete_resource(Req, State) -> {ok, Bucket} = maps:find(bucket, State), User = cowboy_req:binding(username, Req), case dudeswave_auth:delete(User, Bucket) of ok -> {true, Req, State}; {error, _} -> {false, Req, State} end. delete_completed(Req, State) -> {false, Req, State}. % % Custom callbacks % create_user(Req, State) -> {ok, Bucket} = maps:find(bucket, State), User = cowboy_req:binding(username, Req), #{<<"password">> := Pass, <<"email">> := Email} = json:decode(cowboy_req:body(req)), case dudeswave_auth:new_user(User, Pass, Email, Bucket) of ok -> {true, Req, []}; {error, Reason} -> {false, Req, Reason} end. modify_user(Req, State) -> {ok, Bucket} = maps:find(bucket, State), User = cowboy_req:binding(username, Req), #{<<"email">> := Email, <<"description">> := Desc, <<"name">> := Name} = json:decode(cowboy_req:body(req)), case dudeswave_auth:update(User, Name, Email, Desc, Bucket) of ok -> {true, Req, []}; {error, Reason} -> {false, Req, Reason} end. user_details(Req, State) -> #{details := Details} = State, Data = Details#{user => cowboy_req:binding(username, Req)}, {iolist_to_binary(json:encode(Data)), Req, State}. % % gen_server callbacks % terminate(_Reason, _Req, _State) -> ok.