Error handling methodology - adamcath/awsfs GitHub Wiki
The main entry points to awsfs are:
- The CLI command
awsfs
. - The upcalls from the kernel, to FUSE (the userland filesystem driver), to awsfs.
Error handling in the CLI is straightforwards: log errors to stderr and return non-zero. Fail early so the user knows what's going on.
The FUSE entrypoints are more interesting. If you let an exception bubble out of your FUSE operations, the filesystem call will return zero (!) but with no results. I suspect this can lead to downstream memory errors, as the caller thinks the function succeeded but we never actually populated any results. In any case, that's bad. So here are the rules:
- Exceptions never bubble out of
AwsOps
. This is enforced byAwsOps.__call__()
, which wraps every operation in atry/except
. - Operations can handle their own errors and then raise
FuseOSError(errno)
. You may also want to log the details. - Because boto's error handling is such a mess, we have handled many common errors within the wrapper. If you are writing an operation and you can see that
awsfs.to_fuse_ex()
will correctly handle your error then you can let the raw error bubble out of your operation (and test it). - If the wrapper doesn't know what to do, it crashes
awsfs
withos.abort()
, which unmounts the filesystem and creates a core dump for later debugging (provided the system hasulimit -c
set to a high value, which is enragingly not the default on OS X). - Even if you let the wrapper handle your errors, you still have to consider the transactional semantics of an operation (e.g. failure should probably be atomic).
Conventions for log level:
CRITICAL/FATAL
: The next line of code isos.abort()
.ERROR
: There is a bug in awsfs itself, but not worth crashing for.WARNING
: The user needs to know there may be a problem with their configuration which may be actionable.INFO
: An operation failed and the log message may help the user understand why.DEBUG
: An operation failed, there's little chance that a user cares or wants to know why, but developers might care for debugging purposes.