Document adapter error handling requirements and add propagation tests

[Copilot]

Users cannot catch adapter errors with pcall() when using database adapters (e.g., PostgreSQL with wrong credentials). Errors appear in logs but pcall() returns success. Root cause: adapters log errors instead of raising them.

Changes

Interface Documentation

• Add @raises requirement to Adapter and FilteredAdapter interface methods
• Specify adapters MUST use error() on failure, not just logging

User Documentation

• Add "Error Handling for Adapters" section with concrete example:

function MyAdapter:loadPolicy(model)
    local conn, err = connect_to_database(self.config)
    if not conn then
        error("Database connection failed: " .. tostring(err))
    end
end

• Add troubleshooting section for third-party adapters that don't raise errors

Test Coverage

• Add tests/persist/error_handling_spec.lua verifying errors propagate through:
  • Enforcer initialization (auto-loadPolicy)
  • Explicit loadPolicy() calls
  • loadFilteredPolicy() calls

Note

lua-casbin core code already propagates errors correctly. This documents the contract so adapter implementations follow it.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>can't catch error</issue_title>
<issue_description>I use casbin.postgresql adapter

local ok, err = pcall(function()
    local a = Adapter:new(pg_conf, "auth_casbin_rule")
    local ef = Enforcer:new("/usr/local/openresty/nginx/conf/lua/casbin/rbac_model_dom.conf", a)
    ef:loadPolicy()
end)

when I use a wrong password in pg_conf, it will get a error in error.log file,
but I can't get the error with pcall like above, it always get ok. </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes can't catch error #164

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}