Add ACE principals API

Author: D4isDAVID

docs/api/data.md

@@ -161,6 +161,44 @@ User ID, or a player with the given Data ID is currently connected.
 
 - `boolean` - Whether the migration was successful.
 
+### Add Data ID Principal
+
+```
+exports.d4_playerdata:addDataIdPrincipal(dataId, principal)
+```
+
+Persists a given ACE principal to a given Data ID and returns whether it was
+successful.
+Returns `false` if the principal already exists for the given Data ID.
+
+#### Parameters
+
+- `dataId: integer` - The Data ID.
+- `principal: string` - The ACE Principal.
+
+#### Returns
+
+- `boolean` - Whether the principal was added.
+
+### Remove Data ID Principal
+
+```
+exports.d4_playerdata:removeDataIdPrincipal(dataId, principal)
+```
+
+Removes a given ACE principal from a given Data ID and returns whether it was
+successful.
+Returns `false` if the principal does not exist for the given Data ID.
+
+#### Parameters
+
+- `dataId: integer` - The Data ID.
+- `principal: string` - The ACE Principal.
+
+#### Returns
+
+- `boolean` - Whether the principal was removed.
+
 ### Get User ID from Data ID
 
 ```

docs/api/users.md

@@ -129,6 +129,44 @@ Data ID.
 
 - `boolean` - Whether the migration was successful.
 
+### Add User ID Principal
+
+```
+exports.d4_playerdata:addUserIdPrincipal(userId, principal)
+```
+
+Persists a given ACE principal to a given User ID and returns whether it was
+successful.
+Returns `false` if the principal already exists for the given User ID.
+
+#### Parameters
+
+- `userId: integer` - The User ID.
+- `principal: string` - The ACE Principal.
+
+#### Returns
+
+- `boolean` - Whether the principal was added.
+
+### Remove User ID Principal
+
+```
+exports.d4_playerdata:removeUserIdPrincipal(userId, principal)
+```
+
+Removes a given ACE principal from a given User ID and returns whether it was
+successful.
+Returns `false` if the principal does not exist for the given User ID.
+
+#### Parameters
+
+- `userId: integer` - The User ID.
+- `principal: string` - The ACE Principal.
+
+#### Returns
+
+- `boolean` - Whether the principal was removed.
+
 ### Get User ID from Identifier
 
 ```

server/api/data.lua

@@ -46,7 +46,12 @@ function API.data.assign(player, dataId)
     playerToDataId[player] = dataId
     dataIdToPlayer[dataId] = player
 
+    local principals = Storage.dataToPrincipal.getAll(dataId)
+    for i = 1, #principals do
+        Utils.addDataPrincipal(dataId, principals[i])
+    end
     Utils.addPlayerPrincipal(player, Utils.getDataAceName(dataId))
+
     if resource == nil then
         print(('Player %s (User ID %s) was auto-assigned Data ID %s')
             :format(player, userId, dataId))
@@ -72,7 +77,13 @@ function API.data.unassign(player)
 
     playerToDataId[source] = nil
     dataIdToPlayer[dataId] = nil
+
     Utils.removePlayerPrincipal(player, Utils.getDataAceName(dataId))
+    local principals = Storage.dataToPrincipal.getAll(dataId)
+    for i = 1, #principals do
+        Utils.removeDataPrincipal(dataId, principals[i])
+    end
+
     print(('Player %s (User ID %s) was unassigned Data ID %s')
         :format(player, API.users.get(player), dataId))
     TriggerEvent('d4_playerdata:dataUnassigned', player, dataId)
@@ -143,6 +154,42 @@ function API.data.migrate(dataId, newUserId)
     return true
 end
 
+---@param dataId integer
+---@param principal string
+---@return boolean success
+function API.data.addPrincipal(dataId, principal)
+    if Storage.dataToPrincipal.exists(dataId, principal) then
+        return false
+    end
+
+    Storage.dataToPrincipal.set(dataId, principal)
+    FlushResourceKvp()
+
+    if API.data.getPlayer(dataId) ~= nil then
+        Utils.addDataPrincipal(dataId, principal)
+    end
+
+    return true
+end
+
+---@param dataId integer
+---@param principal string
+---@return boolean success
+function API.data.removePrincipal(dataId, principal)
+    if not Storage.dataToPrincipal.exists(dataId, principal) then
+        return false
+    end
+
+    Storage.dataToPrincipal.delete(dataId, principal)
+    FlushResourceKvp()
+
+    if API.data.getPlayer(dataId) ~= nil then
+        Utils.removeUserPrincipal(dataId, principal)
+    end
+
+    return true
+end
+
 ---@param player unknown
 ---@return integer? dataId
 function API.data.autoAssign(player)
@@ -197,3 +244,5 @@ exports('unassignDataId', API.data.unassign)
 exports('createDataId', API.data.create)
 exports('deleteDataId', API.data.delete)
 exports('migrateDataId', API.data.migrate)
+exports('addDataIdPrincipal', API.data.addPrincipal)
+exports('removeDataIdPrincipal', API.data.removePrincipal)

server/api/persist.lua

@@ -111,9 +111,9 @@ local function migrate(oldPersistId, newPersistId)
 end
 
 ---@param player unknown
----@param createMissing boolean
+---@param connecting boolean?
 ---@return integer? persistId
-function API.persist.ensure(player, createMissing)
+function API.persist.ensure(player, connecting)
     player = tostring(player)
 
     local tokens = Utils.getTokens(player)
@@ -128,7 +128,7 @@ function API.persist.ensure(player, createMissing)
 
     local persistId = persistIds[1]
     if persistId == nil then
-        if not createMissing then
+        if connecting then
             return nil
         end
 
@@ -145,13 +145,15 @@ function API.persist.ensure(player, createMissing)
         API.persist.linkUser(persistId, userIds[i])
     end
 
-    playerToPersistId[player] = persistId
-    if persistIdToPlayers[persistId] == nil then
-        persistIdToPlayers[persistId] = {}
-    end
-    persistIdToPlayers[persistId][player] = true
+    if not connecting then
+        playerToPersistId[player] = persistId
+        if persistIdToPlayers[persistId] == nil then
+            persistIdToPlayers[persistId] = {}
+        end
+        persistIdToPlayers[persistId][player] = true
 
-    print(('Player %s was assigned Persist ID %s'):format(player, persistId))
+        print(('Player %s was assigned Persist ID %s'):format(player, persistId))
+    end
     FlushResourceKvp()
 
     return persistId

server/api/users.lua

@@ -132,6 +132,42 @@ function API.users.migrate(oldUserId, newUserId)
     return true
 end
 
+---@param userId integer
+---@param principal string
+---@return boolean success
+function API.users.addPrincipal(userId, principal)
+    if Storage.userToPrincipal.exists(userId, principal) then
+        return false
+    end
+
+    Storage.userToPrincipal.set(userId, principal)
+    FlushResourceKvp()
+
+    if API.users.isConnected(userId) then
+        Utils.addUserPrincipal(userId, principal)
+    end
+
+    return true
+end
+
+---@param userId integer
+---@param principal string
+---@return boolean success
+function API.users.removePrincipal(userId, principal)
+    if not Storage.userToPrincipal.exists(userId, principal) then
+        return false
+    end
+
+    Storage.userToPrincipal.delete(userId, principal)
+    FlushResourceKvp()
+
+    if API.users.isConnected(userId) then
+        Utils.removeUserPrincipal(userId, principal)
+    end
+
+    return true
+end
+
 ---@param player unknown
 ---@return integer? userId
 function API.users.ensure(player)
@@ -183,10 +219,15 @@ function API.users.ensure(player)
         end
     end
 
+    local principals = Storage.userToPrincipal.getAll(userId)
+    for i = 1, #principals do
+        Utils.addUserPrincipal(userId, principals[i])
+    end
     Utils.addPlayerPrincipal(player, Utils.getUserAceName(userId))
-    print(('Player %s was assigned User ID %s'):format(player, userId))
 
+    print(('Player %s was assigned User ID %s'):format(player, userId))
     FlushResourceKvp()
+
     if created then
         TriggerEvent('d4_playerdata:userCreated', userId)
     end
@@ -211,6 +252,11 @@ function API.users.remove(player)
     end
 
     Utils.removePlayerPrincipal(player, Utils.getUserAceName(userId))
+    local principals = Storage.userToPrincipal.getAll(userId)
+    for i = 1, #principals do
+        Utils.removeUserPrincipal(userId, principals[i])
+    end
+
     print(('Player %s was unassigned User ID %s'):format(player, userId))
     TriggerEvent('d4_playerdata:userLeft', player, userId)
 end
@@ -222,3 +268,5 @@ exports('isUserIdConnected', API.users.isConnected)
 exports('getPlayersFromUserId', API.users.getPlayers)
 exports('deleteUserId', API.users.delete)
 exports('migrateUserId', API.users.migrate)
+exports('addUserIdPrincipal', API.users.addPrincipal)
+exports('removeUserIdPrincipal', API.users.removePrincipal)

server/storage/data/dataToPrincipal.lua

@@ -0,0 +1,41 @@
+Storage.dataToPrincipal = {}
+
+local rootKey = 'dataToPrincipal:'
+
+---@param dataId integer
+---@param principal string?
+---@return string key
+local function key(dataId, principal)
+    return rootKey .. tostring(dataId) .. ':' .. (principal or '')
+end
+
+---@param dataId integer
+---@param principal string
+---@return boolean exists
+function Storage.dataToPrincipal.exists(dataId, principal)
+    return GetResourceKvpString(key(dataId, principal)) ~= nil
+end
+
+---@param dataId integer
+---@return string[] principals
+function Storage.dataToPrincipal.getAll(dataId)
+    local principals = {}
+
+    Utils.searchKvp(key(dataId), function(idKey)
+        principals[#principals + 1] = GetResourceKvpString(idKey)
+    end)
+
+    return principals
+end
+
+---@param dataId integer
+---@param principal string
+function Storage.dataToPrincipal.set(dataId, principal)
+    SetResourceKvpNoSync(key(dataId, principal), principal)
+end
+
+---@param dataId integer
+---@param principal string
+function Storage.dataToPrincipal.delete(dataId, principal)
+    DeleteResourceKvpNoSync(key(dataId, principal))
+end

server/storage/users/userToPrincipal.lua

@@ -0,0 +1,41 @@
+Storage.userToPrincipal = {}
+
+local rootKey = 'userToPrincipal:'
+
+---@param userId integer
+---@param principal string?
+---@return string key
+local function key(userId, principal)
+    return rootKey .. tostring(userId) .. ':' .. (principal or '')
+end
+
+---@param userId integer
+---@param principal string
+---@return boolean exists
+function Storage.userToPrincipal.exists(userId, principal)
+    return GetResourceKvpString(key(userId, principal)) ~= nil
+end
+
+---@param userId integer
+---@return string[] principals
+function Storage.userToPrincipal.getAll(userId)
+    local principals = {}
+
+    Utils.searchKvp(key(userId), function(idKey)
+        principals[#principals + 1] = GetResourceKvpString(idKey)
+    end)
+
+    return principals
+end
+
+---@param userId integer
+---@param principal string
+function Storage.userToPrincipal.set(userId, principal)
+    SetResourceKvpNoSync(key(userId, principal), principal)
+end
+
+---@param userId integer
+---@param principal string
+function Storage.userToPrincipal.delete(userId, principal)
+    DeleteResourceKvpNoSync(key(userId, principal))
+end