// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.blobfs;

using zx;

// Describes contiguous run of allocated blocks.
struct BlockRegion {
    uint64 offset;
    uint64 length;
};

[Layout = "Simple"]
protocol Blobfs {
    // Retrieve information about allocated regions on the filesystem.
    GetAllocatedRegions() -> (zx.status status, handle<vmo>? regions, uint64 count);
};

[Layout = "Simple"]
protocol BlobfsAdmin {
    HandleCorruptBlobs(CorruptBlobHandler handler) -> (zx.status status);
};

// Action to be taken on blob corruption.
// Depending on the "type" of blob (i.e system critical/non critical),
// CorruptBlobHandler can instruct blobfs to take appropriate action on the blob.
enum TakeAction : uint8 {
    // Return error without deleting.
    RETURN_ERROR = 0;

    // Delete the blob and hang execution.
    DELETE_AND_HANG = 1;

    // Delete the blob and return error.
    DELETE_AND_RETURN_ERROR = 2;
};

[Layout = "Simple"]
protocol CorruptBlobHandler {
    // A corruption handler may determine that a blob is sufficiently critical that returning errors
    // to clients may lead to undesirable system configuration or behavior. In this case the handler
    // may return DELETE_AND_HANG to prevent such an event. As this behavior effectively leaks
    // resources, it is expected that the corruption handler otherwise arranges that the system will
    // be restarted/recovered.
    // For non critical blobs, CorruptBlob will return with a DELETE_AND_RETURN_ERROR or
    // RETURN_ERROR, and the read may "continue" i.e an error will be observed by the blobfs
    // client that is reading.
    CorruptBlob(vector<uint8>:64 merkleroot) -> (TakeAction action);
};