xtreemfs/interface/xtreemfs/GlobalTypes.proto

//
// Copyright (c) 2009-2011, Konrad-Zuse-Zentrum fuer Informationstechnik Berlin
//
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
// Redistributions of source code must retain the above copyright notice, this
// list of conditions and the following disclaimer.
// Redistributions in binary form must reproduce the above copyright notice,
// this list of conditions and the following disclaimer in the documentation
// and/or other materials provided with the distribution.
// Neither the name of the Konrad-Zuse-Zentrum fuer Informationstechnik Berlin
// nor the names of its contributors may be used to endorse or promote products
// derived from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//
// AUTHORS: Bjoern Kolbeck (ZIB), Jan Stender (ZIB)
//

option java_package="org.xtreemfs.pbrpc.generatedinterfaces";
package xtreemfs.pbrpc;
import "include/PBRPC.proto";
import "include/Common.proto";

// Access control policy for a volume.
enum AccessControlPolicyType {
  // No access control.
  ACCESS_CONTROL_POLICY_NULL = 1;
  // Regular POSIX permission and ACL-based access control.
  ACCESS_CONTROL_POLICY_POSIX = 2;
  // Permissions per volume (instead of per directory),
  // faster since hierarchical evaluation is skipped.
  ACCESS_CONTROL_POLICY_VOLUME = 3;
}

// Values for OSD (and Replica) selection policies.
enum OSDSelectionPolicyType {
    // Default filter.
    OSD_SELECTION_POLICY_FILTER_DEFAULT = 1000;
    // Filter based on the domain name (FQDN) of OSDs.
    OSD_SELECTION_POLICY_FILTER_FQDN = 1001;
    // Filter based on the UUID of OSDs.
    OSD_SELECTION_POLICY_FILTER_UUID = 1002;
    // Groups OSDs according to their location in the
    // datacenter map.
    OSD_SELECTION_POLICY_GROUP_DCMAP = 2000;
    // Groups OSDs accroding to their domain names.
    OSD_SELECTION_POLICY_GROUP_FQDN = 2001;
    // Sorts the OSDs by distance from client calculated
    // using the datacenter map.
    OSD_SELECTION_POLICY_SORT_DCMAP = 3000;
    // Sorts the OSDs by longest postfix match of the FQDN
    // of OSD and client.
    OSD_SELECTION_POLICY_SORT_FQDN = 3001;
    // Random order.
    OSD_SELECTION_POLICY_SORT_RANDOM = 3002;
    // Sorts the OSDs by proximity of vivalid network
    // coordinates of the client.
    OSD_SELECTION_POLICY_SORT_VIVALDI = 3003;
    // Sorts the OSDs in a round robin manner for
    // multiple OSDs per host.
    OSD_SELECTION_POLICY_SORT_HOST_ROUND_ROBIN = 3004;
    // Sortes the OSDs by their UUID.
    OSD_SELECTION_POLICY_SORT_UUID = 3998;
    // Reverse given list. Used only internally by unit tests.
    OSD_SELECTION_POLICY_SORT_REVERSE = 3999;
}
      
enum ReplicaSelectionPolicyType {
  REPLICA_SELECTION_POLICY_SIMPLE = 1;
}

// Configuration for file data snapshots.
enum SnapConfig {
  // Indicates that snapshots are disabled.
  SNAP_CONFIG_SNAPS_DISABLED = 0;
  // Indicates access to the current version of a file.
  SNAP_CONFIG_ACCESS_CURRENT = 1;
  // Indicates access to a snapshot of a file.
  SNAP_CONFIG_ACCESS_SNAP = 2;
}

// File size update data sent by OSDs.
message NewFileSize {
    // New file size in bytes.
    required fixed64  size_in_bytes = 1;
    // Truncate epoch to sort file size updates.
    required fixed32  truncate_epoch = 2;
}

enum StripingPolicyType {
    // Default striping policy (round-robin distribution).
    STRIPING_POLICY_RAID0 = 0;
    // Erasure code striping policy (.
    STRIPING_POLICY_ERASURECODE = 1;
}

message StripingPolicy {
    // Type (by default STRIPING_POLICY_RAID0).
    required StripingPolicyType type = 1;
    // Size of a single chunk (object) in *kB*!
    // The name of the field is wrong: This is not the total size of the stripe.
    // Instead, the total size of a stripe in XtreemFS is: stripe_size * (width + parity_width)
    required fixed32 stripe_size = 2;
    // Number of OSDs to distribute data chunks on.
    required fixed32 width = 3;
    // Number of OSDs to distribute parity chunks on.
    optional fixed32 parity_width = 4;
}

// Details for a file replica.
message Replica {
    // UUIDs of OSDs to store objects on.
    // Length of this list must be equal to width
    // in striping_policy!
    repeated string osd_uuids = 1;
    // Flags to control replication, e.g. transfer strategy.
    required fixed32 replication_flags = 2;
    // Striping policy for this replica.
    required StripingPolicy striping_policy = 3;
}

// List of replicas for a file.
message Replicas {
  repeated Replica replicas = 1;
}

// The LeaseState for a Replica.
enum LeaseState {
  // The replica's update policy is not using lease.
  NONE = 0;
  // The replica is the the primary.
  PRIMARY = 1;
  // The replica is a backup (and an active primary exists).
  BACKUP = 2;
  // The replica is not active (currently no lease exists).
  IDLE = 3;
}

// The XCap is the authorization token that allows a 
// client to execute operations on an OSD. It is created
// by the MRC on open and must be renewed by the client
// *before* it times out.
// The XCap is signed and must not be modified by a client.
message XCap {
  // Access mode (see SYSTEM_V_FCNTL for allowed values).
  required fixed32 access_mode = 1;
  // IP address of the client that owns this XCap.
  required string client_identity = 2;
  // Number of seconds this XCap is valid.
  required fixed64 expire_time_s = 3;
  // Timestamp in global synchronized XtreemFS time when
  // the XCap expires.
  required fixed32 expire_timeout_s = 4;
  // FileID for which this XCap is valid.
  required string file_id = 5;
  // True, if the file should be replicated when
  // closed (read-only replication).
  required bool replicate_on_close = 6;
  // MRC server signature, based on various fields of the XCap.
  required string server_signature = 7;
  // Current truncate_epoch for the file, required by OSDs.
  required fixed32 truncate_epoch = 8;
  // Snapshot configuration for the file, required by OSDs.
  required SnapConfig snap_config = 9;
  // If a snapshot of the file is being accessed, this timestamp
  // indicates which version (snapshot) of the file should be used
  // on the OSD.
  required fixed64 snap_timestamp = 10;
}

// Locations of a file, i.e. the list of replicas including the OSDs that hold
// the file data.
message XLocSet {
  // Used by the read-only replication to properly handle
  // holes in sparse files and EOF.
  required fixed64 read_only_file_size = 1;
  // List of actual file replicas.
  repeated Replica replicas = 2;
  // Update policy to use for the file,
  // see org.xtreemfs.common.ReplicaUpdatePolicies for values.
  required string replica_update_policy = 3;
  // Monotonically increasing version number of a file's XLocSet.
  // Used to identify clients with outdates XLocSets.
  required fixed32 version = 4;        
}

// Information required by OSDs for all file operations.
message FileCredentials {
  required XCap xcap = 1;
  required XLocSet xlocs = 2;
}

message FileCredentialsSet {
  optional FileCredentials file_credentials = 1;
}

// Network coordinates to estimate the latency.
message VivaldiCoordinates {
  required double x_coordinate = 1;
  required double y_coordinate = 2;
  required double local_error = 3;
}

// Response returned by OSD write and truncate operations.
// This information is stored by the client and must be
// relayed to the MRC in regular intervals or when the file
// is fsynced or closed.
// In addition, the client must use this information locally
// for open files to provide processes with an accurate
// file size.
// Clients only need to store and relay the most recent OSDWriteResponse.
// These are sorted first by truncate_epoch and then by size_in_bytes, both ascending.
message OSDWriteResponse {
  // Current file size in bytes.
  optional fixed64 size_in_bytes = 1;
  // Truncate epoch.
  optional fixed32 truncate_epoch = 2;
}

// TCP ports used by the services.
// HTTP ports are used for the status pages.
enum PORTS {
  DIR_HTTP_PORT_DEFAULT = 30638; 
  DIR_PBRPC_PORT_DEFAULT = 32638;
  MRC_HTTP_PORT_DEFAULT = 30636; 
  MRC_PBRPC_PORT_DEFAULT = 32636;
  OSD_HTTP_PORT_DEFAULT = 30640; 
  OSD_PBRPC_PORT_DEFAULT = 32640;
}

// Renew interval for clients.
enum CONSTANTS {
  XCAP_RENEW_INTERVAL_IN_MIN = 1;
}

// Flags for open command and access mode.
// Values are Linux, might be different for other platforms!
enum SYSTEM_V_FCNTL {
  SYSTEM_V_FCNTL_H_O_RDONLY = 0x0000;
  SYSTEM_V_FCNTL_H_O_WRONLY = 0x0001;
  SYSTEM_V_FCNTL_H_O_RDWR = 0x0002;
  SYSTEM_V_FCNTL_H_O_APPEND = 0x0008;
  SYSTEM_V_FCNTL_H_O_CREAT = 0x0100;
  SYSTEM_V_FCNTL_H_O_TRUNC = 0x0200;
  SYSTEM_V_FCNTL_H_O_EXCL = 0x0400;
  SYSTEM_V_FCNTL_H_O_SYNC = 0x0010;
  SYSTEM_V_FCNTL_H_S_IFREG = 0x8000;
  SYSTEM_V_FCNTL_H_S_IFDIR = 0x4000;
  SYSTEM_V_FCNTL_H_S_IFLNK = 0xA000;
  SYSTEM_V_FCNTL_H_S_IFIFO = 0x1000;
}

// Flags for replication, multiple flags can be
// OR'ed.
enum REPL_FLAG {
  REPL_FLAG_FULL_REPLICA = 1;
  REPL_FLAG_IS_COMPLETE = 2;
  REPL_FLAG_STRATEGY_RANDOM = 4;
  REPL_FLAG_STRATEGY_RAREST_FIRST = 8;
  REPL_FLAG_STRATEGY_SEQUENTIAL = 16;
  REPL_FLAG_STRATEGY_SEQUENTIAL_PREFETCHING = 32;
}

// Simple key/value pair. Protobuf doesn't provide a map type.
message KeyValuePair {
  required string key = 1;
  required string value = 2;
}

enum SERVICES {
  DIR = 1;
  MRC = 2;
  OSD = 3;
}