Error handling methodology - adamcath/awsfs GitHub Wiki

The main entry points to awsfs are:

  1. The CLI command awsfs.
  2. 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:

  1. Exceptions never bubble out of AwsOps. This is enforced by AwsOps.__call__(), which wraps every operation in a try/except.
  2. Operations can handle their own errors and then raise FuseOSError(errno). You may also want to log the details.
  3. 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).
  4. If the wrapper doesn't know what to do, it crashes awsfs with os.abort(), which unmounts the filesystem and creates a core dump for later debugging (provided the system has ulimit -c set to a high value, which is enragingly not the default on OS X).
  5. 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:

  1. CRITICAL/FATAL: The next line of code is os.abort().
  2. ERROR: There is a bug in awsfs itself, but not worth crashing for.
  3. WARNING: The user needs to know there may be a problem with their configuration which may be actionable.
  4. INFO: An operation failed and the log message may help the user understand why.
  5. DEBUG: An operation failed, there's little chance that a user cares or wants to know why, but developers might care for debugging purposes.