Draft: Servant Api Specification

This PR does 3 things:

1. Specifies a modular definition for the Skete Servant api, along with associated clients and server. The design is granular to facilitate better testing (standalone clients are easier to test when their component apis are separate from the rest of the API)

2. Restructures the project to define a toplevel RestAPI.hs module, with client/server/util definitions in an associated RestAPI/* namespace.

3. Adds the Servant-* dependencies, cleans up old code.

Addresses #21

src/Distribution/Skete/Haskell/API/Features/Users.hs

+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE TypeOperators #-}
+module Distribution.Skete.Haskell.API.Features.Users
+( -- * User API
+  UsersApi(..)
+, usersApi
+, usersApiHandlers
+  -- ** User endpoints
+, GetUsersApi
+, getUsersApi
+, PostUsersApi
+, postUsersApi
+  -- ** User id endpoints
+, GetUserIdApi
+, getUserIdApi
+, PutUserIdApi
+, putUserIdApi
+, DeleteUserIdApi
+, deleteUserIdApi
+  -- ** User password endpionts
+, GetUserPasswordApi
+, getUserPasswordApi
+, PutUserPasswordApi
+, putUserPasswordApi
+  -- ** User enabled endpoints
+, GetUserEnabledApi
+, getUserEnabledApi
+, PutUserEnabledApi
+, putUserEnabledApi
+  -- ** User management endpoints
+, GetUserManagementApi
+, getUserManagementApi
+  -- ** User account management endpoincts
+, GetUserAccountManagementApi
+, getUserAccountManagementApi
+  -- ** User admin endpoints
+, GetUserAdminsApi
+, getUserAdminsApi
+, PutUserAdminsApi
+, putUserAdminsApi
+, PostUserAdminsApi
+, postUserAdminsApi
+, DeleteUserAdminsApi
+, deleteUserAdminsApi
+) where
+
+
+import Data.Proxy
+import Data.Text
+
+import Distribution.Skete.Haskell.API.Types.Users
+import GHC.Generics
+
+import Servant
+import Servant.API.Generic
+import Servant.HTML.Blaze
+import Servant.Server.Generic
+
+-- -------------------------------------------------------------------------- --
+-- Users API definition
+
+-- | The Users Hackage api.
+--
+-- This Api allows Hackage processes to manipulate the user database. Routes
+-- are prefixed with "users" at the when hooked up to the hackage server.
+--
+-- State:
+--
+--   * List of users
+--   * Admins
+--
+data UsersApi route
+  = UsersApi
+  { getUsers                 :: route :- GetUsersApi
+  , postUsers                :: route :- PostUsersApi
+  , getUserId                :: route :- GetUserIdApi
+  , putUserId                :: route :- PutUserIdApi
+  , deleteUserId             :: route :- DeleteUserIdApi
+  , getUserPassword          :: route :- GetUserPasswordApi
+  , putUserPassword          :: route :- PutUserPasswordApi
+  , getUserEnabled           :: route :- GetUserEnabledApi
+  , putUserEnabled           :: route :- PutUserEnabledApi
+  , getUserManagement        :: route :- GetUserManagementApi
+  , getUserAccountManagement :: route :- GetUserAccountManagementApi
+  , getUserAdmins            :: route :- GetUserAdminsApi
+  , postUserAdmins           :: route :- PostUserAdminsApi
+  , putUserAdmins            :: route :- PutUserAdminsApi
+  , deleteUserAdmins         :: route :- DeleteUserAdminsApi
+  } deriving Generic
+
+-- | Singleton instance for 'UsersApi'.
+--
+usersApi :: Proxy (ToServantApi UsersApi)
+usersApi = genericApi (Proxy :: Proxy UsersApi)
+
+-- | Users Api Handlers.
+--
+-- TODO: Stubbed in Distribution.Skete.Haskell.API.Features.Users.Server
+--
+usersApiHandlers :: UsersApi AsServer
+usersApiHandlers = UsersApi
+  { getUsers = error "TODO: handler not yet written"
+  , postUsers = error "TODO: handler not yet written"
+  , getUserId = error "TODO: handler not yet written"
+  , putUserId = error "TODO: handler not yet written"
+  , deleteUserId = error "TODO: handler not yet written"
+  , getUserPassword = error "TODO: handler not yet written"
+  , putUserPassword = error "TODO: handler not yet written"
+  , getUserEnabled = error "TODO: handler not yet written"
+  , putUserEnabled = error "TODO: handler not yet written"
+  , getUserManagement = error "TODO: handler not yet written"
+  , getUserAccountManagement = error "TODO: handler not yet written"
+  , getUserAdmins = error "TODO: handler not yet written"
+  , postUserAdmins = error "TODO: handler not yet written"
+  , putUserAdmins = error "TODO: handler not yet written"
+  , deleteUserAdmins = error "TODO: handler not yet written"
+  }
+
+-- -------------------------------------------------------------------- --
+-- GET /users
+
+-- | Equivalent to "GET /users/": accepts a GET request and returns all
+-- registered Hackage users as JSON.
+--
+type GetUsersApi
+  = Summary "Get a list of users"
+  :> Description "Get a list of all currently registered Hackage users \
+                 \as either JSON or HTML."
+  :> "users"
+  :> Get '[JSON, HTML] [UserName]
+
+-- | Singleton instance for 'GetUsersApi'.
+--
+getUsersApi :: Proxy GetUsersApi
+getUsersApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- POST /users
+
+-- | Equivalent to "POST /users/": accepts a POST request to create
+-- a new hackage user using HTML.
+--
+type PostUsersApi
+  = Summary "Create a new user."
+  :> Description "Create a new Hackage user via html POST request."
+  :> "users"
+  :> ReqBody '[HTML] UserInfo
+  :> Post '[HTML] UserInfo
+
+-- | Singleton instance for 'PostUsersApi'.
+--
+postUsersApi :: Proxy PostUsersApi
+postUsersApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- GET /users/:username
+
+-- | Equivalent to "GET /users/:username": accepts a GET request for the
+-- user id info for a particular hackage user as JSON or HTML.
+--
+type GetUserIdApi
+  = Summary "Get user id info."
+  :> Description "Get user id info for a particular Hackage user."
+  :> "users"
+  :> Capture "username" UserId
+  :> Get '[JSON, HTML] UserInfo
+
+-- | Singleton instance for 'GetUeserIdApi'.
+--
+getUserIdApi :: Proxy GetUserIdApi
+getUserIdApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- PUT /users/:username
+
+
+-- | Equivalent to "PUT /users/:username": accepts a PUT request to
+-- create a new user as JSON.
+--
+type PutUserIdApi
+  = Summary "Create user."
+  :> Description "Create a Hackage user."
+  :> "users"
+  :> Capture "username" UserId
+  :> Put '[JSON] UserInfo
+
+
+-- | Singleton instance for 'PostUserIdApi'.
+--
+putUserIdApi :: Proxy PutUserIdApi
+putUserIdApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- DELETE /users/:username
+
+-- | Equivalent to "DELETE /users/:username": accepts a DELETE request
+-- to delete a particular hackage user.
+--
+type DeleteUserIdApi
+  = Summary "Delete user."
+  :> Description "Delete a Hackage user."
+  :> "users"
+  :> Capture "username" UserId
+  :> DeleteNoContent
+
+
+-- | Singleton instance for 'DeleteUserIdApi'.
+--
+deleteUserIdApi :: Proxy DeleteUserIdApi
+deleteUserIdApi = Proxy
+
+
+-- -------------------------------------------------------------------- --
+-- GET /users/:username/password
+
+-- | Equivalent to "GET /users/:username/password": accepts a GET request
+-- to show the password change form as HTML. Note: TODO.
+--
+type GetUserPasswordApi
+  = Summary "Show password change form."
+  :> Description "Show the password change form for a particular Hackage user."
+  :> "users"
+  :> Capture "username" UserId
+  :> "password"
+  :> Get '[HTML] HTML
+
+-- | Singleton instance for 'GetUserPasswordApi'.
+--
+getUserPasswordApi :: Proxy GetUserPasswordApi
+getUserPasswordApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- PUT /users/:username/password
+
+-- | Equivalant to "PUT /users/:username/password": accepts a PUT request
+-- to change the password for a particular use as HTML. Note: TODO.
+--
+type PutUserPasswordApi
+  = Summary "Change password."
+  :> Description "Change password for a Hackage user."
+  :> "users"
+  :> Capture "username" UserId
+  :> "password"
+  :> Put '[HTML] Text
+
+
+-- | Singleton instance for 'PostUserPasswordApi'.
+--
+putUserPasswordApi :: Proxy PutUserPasswordApi
+putUserPasswordApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- GET /users/:username/enabled
+
+-- | Equivalent to "GET /users/:username/enabled": accepts a GET request
+-- to check if a particular Hackage user is enabled as JSON.
+--
+type GetUserEnabledApi
+  = Summary "Return if the user is enabled."
+  :> Description "Return if the user is enabled for a particular Hackage user."
+  :> "users"
+  :> Capture "username" UserId
+  :> "enabled"
+  :> Get '[JSON] Bool
+
+-- | Singleton instance for 'GetUserEnabledApi'.
+--
+getUserEnabledApi :: Proxy GetUserEnabledApi
+getUserEnabledApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- PUT /users/:username/enabled
+
+-- | Equivalant to "POST /users/:username/enabled": accepts a POST request
+-- to enable a particular Hackage user as JSON.
+--
+type PutUserEnabledApi
+  = Summary "Enable a user."
+  :> Description "Set a Hackage user to \"enabled\"."
+  :> "users"
+  :> Capture "username" UserId
+  :> "enabled"
+  :> ReqBody '[JSON] UserStatus
+  :> Post '[JSON] UserStatus
+
+-- | Singleton instance for 'PutUserEnabledApi'.
+--
+putUserEnabledApi :: Proxy PutUserEnabledApi
+putUserEnabledApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- GET /users/:username/manage
+
+-- | Equivalant to "GET /users/:username/manage": accepts a GET request
+-- to return the user management page for Hackage user as HTML. Note: TODO
+--
+type GetUserManagementApi
+  = Summary "Get user management page."
+  :> Description "Get user management page for a Hackage user."
+  :> "users"
+  :> Capture "username" UserId
+  :> "manage"
+  :> Get '[HTML] HTML
+
+-- | Singleton instance for 'GetUserManagementApi'.
+--
+getUserManagementApi :: Proxy GetUserManagementApi
+getUserManagementApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- GET /users/:username/account-management
+
+-- | Equivalent to "GET /users/:username/account-management": accepts a GET
+-- request for a Hackage user's personal account management page as HTML.
+-- Note: TODO
+--
+type GetUserAccountManagementApi
+  = Summary "Get user's personal account management page."
+  :> Description "Get a Hackage user's personal account management page."
+  :> "users"
+  :> Capture "username" UserId
+  :> "account-management"
+  :> Get '[HTML] HTML
+
+-- | Singleton instance for 'GetUserAccountManagementApi'.
+--
+getUserAccountManagementApi :: Proxy GetUserAccountManagementApi
+getUserAccountManagementApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- GET /users/admins
+
+-- | Equivalent to "GET /users/admins": Accepts a GET request for
+-- the list of Hackage administrators as JSON or HTML.
+--
+type GetUserAdminsApi
+  = Summary "Show list of administrators."
+  :> Description "Show the list of Hackage server administrators."
+  :> "users"
+  :> "admins"
+  :> Get '[JSON, HTML] [UserName]
+
+-- | Singleton instance for 'GetUserAdminsApi'.
+--
+getUserAdminsApi :: Proxy GetUserAdminsApi
+getUserAdminsApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- POST /users/admins
+
+-- | Equivalent to "POST /users/admins": Accepts a POST request to
+-- add a user to the list of Hackage admins as HTML. Note: TODO
+--
+type PostUserAdminsApi
+  = Summary "Add an administrator."
+  :> Description "Add a user to the list of Hackage administrators."
+  :> "users"
+  :> "admins"
+  :> ReqBody '[HTML] UserInfo
+  :> Post '[HTML] UserInfo
+
+
+-- | Singleton instance for 'PostUserAdminsApi'.
+--
+postUserAdminsApi :: Proxy PostUserAdminsApi
+postUserAdminsApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- PUT /users/admins
+
+-- | Equivalent to "PUT /users/admins/user/:username": Accepts a PUT
+-- request to add a user to the list of Hackage admins as HTML.
+-- Note: TODO
+--
+type PutUserAdminsApi
+  = Summary "Add an administrator"
+  :> Description "Add a user ot the list of Hackage administrators."
+  :> "users"
+  :> "admins"
+  :> "user"
+  :> Capture "username" UserId
+  :> PutNoContent
+
+
+-- | Singleton instance for 'PutUserAdminsApi'.
+--
+putUserAdminsApi :: Proxy PutUserAdminsApi
+putUserAdminsApi = Proxy
+
+-- -------------------------------------------------------------------- --
+-- DELETE /users/admins
+
+-- | Equivalent to "DELETE /users/admins/user/:username": Accepts a DELETE
+-- request to remove a user to the list of Hackage admins.
+-- Note: TODO
+--
+type DeleteUserAdminsApi
+  = Summary "Remove an administator"
+  :> Description "Remove an administrator from the list of Hackage admins."
+  :> "users"
+  :> "admins"
+  :> "user"
+  :> Capture "username" UserId
+  :> DeleteNoContent
+
+-- | Singleton instance for 'DeleteUserAdminsApi'.
+--
+deleteUserAdminsApi :: Proxy DeleteUserAdminsApi
+deleteUserAdminsApi = Proxy