Unified thrift definitions for master and satellite

1 files changed, 269 insertions, 96 deletions

diff --git a/src/main/thrift/bwlp.thrift b/src/main/thrift/bwlp.thrift
index 4d2a588..c3221c1 100644
--- a/src/main/thrift/bwlp.thrift
+++ b/src/main/thrift/bwlp.thrift
@@ -5,12 +5,16 @@ namespace java org.openslx.bwlp.thrift.iface
  
 typedef i64 int
 
-typedef string ID
+// Use these typedefs if appropriate (to clarify)
 typedef string Token
 typedef string UUID
-typedef string UserID
 typedef i64 UnixTimestamp
 
+// Use *only* strings (or typedefs of string) as keys for a map (map<string, ...>)
+// UpperCamelCase for struct names
+// lowerCamelCase for methods, variables, struct members
+// CAPS_WITH_UNDERSCORE for enum members 
+
 // ################# ENUM ################
 
 enum AuthorizationError {
@@ -34,12 +38,10 @@ enum ImageDataError {
 	UNKNOWN_IMAGE
 }
 
-enum UploadError {
-	INVALID_CRC,
-	BROKEN_BLOCK,
-	GENERIC_ERROR,
-	INVALID_METADATA,
-	ALREADY_COMPLETE
+enum ShareMode {
+	LOCAL,
+	PUBLISH,
+	DOWNLOAD
 }
 
 // ############## STRUCT ###############
@@ -52,21 +54,38 @@ struct UserInfo {
 	5: string organizationId
 }
 
-struct OrganizationData {
+struct Organization {
 	1: string organizationId,
 	2: string displayName,
 	3: string ecpUrl,
 	4: list<string> suffixList,
 }
 
+struct Satellite {
+	1: list<string> addressList,
+	2: string displayName
+}
+
+// Old session information for clients logging in via "test-account"
 struct SessionData {
-	1: ID sessionId,
+	1: Token sessionId,
 	2: Token authToken,
 	3: string serverAddress
 }
 
+struct ClientSessionData {
+	1: Token sessionId,
+	2: Token authToken,
+	3: list<Satellite> satellites
+}
+
 struct ServerSessionData {
-	1: ID sessionId
+	1: Token sessionId
+}
+
+struct Virtualizer {
+	1: string virtId,
+	2: string virtName
 }
 
 struct OperatingSystem {
@@ -76,45 +95,147 @@ struct OperatingSystem {
 	4: string architecture,
 }
 
-struct ImagePermission {
-	1: bool read
-	2: bool write
-	3: bool admin
-	4: bool link
+struct ImagePermissions {
+	1: bool link
+	2: bool download
+	3: bool edit
+	4: bool admin
 }
 
-struct LecturePermission {
-	1: bool write
+struct LecturePermissions {
+	1: bool edit
 	2: bool admin
 }
 
-struct ImageBaseData {
+struct ImageBaseWrite {
+	1: string imageName,
+    2: string description,
+	3: i32 osId,
+	4: bool isTemplate,
+	5: ImagePermissions defaultPermissions,
+	6: ShareMode shareMode,
+	7: optional UUID ownerId,
+}
+
+struct ImagePublishData {
+	1: UUID imageBaseId,
+	2: UUID currentVersionId,
+	3: string imageName,
+	4: i32 osId,
+	5: string virtId,
+	6: UnixTimestamp baseCreateTime,
+	7: UnixTimestamp versionCreateTime,
+	8: UUID ownerId,
+	9: UUID uploaderId,
+	11: i64 fileSize,
+	16: bool isTemplate,
+}
+
+struct ImageVersionWrite {
+	1: bool isEnabled,
+	2: bool isRestricted,
+}
+
+struct ImageSummaryRead {
 	1: UUID imageBaseId,
+	2: UUID currentVersionId,
 	3: string imageName,
-   10: string description,
-	5: i32 osId,
+	4: i32 osId,
+	5: string virtId,
 	6: UnixTimestamp createTime,
 	7: UnixTimestamp updateTime,
-	9: string isTemplate,
+	8: UUID ownerId,
+	9: UUID uploaderId,
+	10: ShareMode shareMode,
+	11: i64 fileSize,
+	12: bool isEnabled,
+	13: bool isRestricted,
+	14: bool isValid,
+	15: bool isProcessed,
+	16: bool isTemplate,
+	17: ImagePermissions defaultPermissions,
+	18: optional ImagePermissions userPermissions,
 }
-struct ImagePermissionCombined {
-	1: Image image,
-	2: ImagePermission permission,
+
+struct ImageVersionDetails {
+	1: UUID versionId,
+	2: UnixTimestamp createTime,
+	3: UnixTimestamp expireTime,
+	4: i64 fileSize,
+	5: UUID uploaderId,
+	6: bool isEnabled,
+	7: bool isRestricted,
+	8: bool isValid,
+	9: bool isProcessed,
 }
 
-struct Lecture {
-	1: optional UUID lectureId,
+struct ImageDetailsRead {
+	1: UUID imageBaseId,
+	2: UUID currentVersionId,
+	3: list<ImageVersionDetails> versions,
+	4: string imageName,
+	5: string description,
+	6: list<string> tags,
+	7: list<string> software,
+	8: i32 osId,
+	9: string virtId,
+	10: UnixTimestamp createTime,
+	11: UnixTimestamp updateTime,
+	12: UUID ownerId,
+	13: UUID updaterId,
+	14: ShareMode shareMode,
+	15: bool isTemplate,
+	16: ImagePermissions defaultPermissions,
+	17: optional ImagePermissions userPermissions,
+}
+
+struct LectureWrite {
+	1: string lectureName,
+	2: string description,
+	3: UUID imageVersionId,
+	4: bool isEnabled,
+	5: UnixTimestamp startTime,
+	6: UnixTimestamp endTime,
+	7: UUID ownerId,
+	8: bool isExam,
+	9: bool hasInternetAccess,
+	10: LecturePermissions defaultPermissions,
+}
+
+struct LectureSummary {
+	1: UUID lectureId,
 	2: string lectureName,
-	3: string isActive,
-	4: UnixTimestamp startTime,
-	5: UnixTimestamp endTime,
-	6: UnixTimestamp lastUsed,
-	7: string description,
-	8: UUID imageId
+	3: UUID imageVersionId,
+	4: string imageName,
+	5: bool isEnabled,
+	6: UnixTimestamp startTime,
+	7: UnixTimestamp endTime,
+	8: UnixTimestamp lastUsed,
+	9: i32 useCount,
+	10: UUID ownerId,
+	11: UUID updaterId,
+	12: bool isExam,
+	13: bool hasInternetAccess,
+	14: LecturePermissions defaultPermissions,
+	15: optional LecturePermissions userPermissions,
 }
-struct LecturePermissionCombined {
-	1: Lecture lecture,
-	2: LecturePermission permission,
+
+struct LectureRead {
+	1: UUID lectureId,
+	2: string lectureName,
+	3: string description,
+	4: ImageSummaryRead image,
+	5: bool isEnabled,
+	6: UnixTimestamp startTime,
+	7: UnixTimestamp endTime,
+	8: UnixTimestamp lastUsed,
+	9: i32 useCount,
+	10: UUID ownerId,
+	11: UUID updaterId,
+	12: bool isExam,
+	13: bool hasInternetAccess,
+	14: LecturePermissions defaultPermissions,
+	15: optional LecturePermissions userPermissions,
 }
 
 struct TransferInformation {
@@ -123,13 +244,13 @@ struct TransferInformation {
 	3: i32 sslPort,
 }
 
-// ############ EXCEPTION ######################
-
-exception TUploadFinishException {
-	1: string reason,
+struct UploadStatus {
+	1: binary blockStatus,
 }
 
-exception TUploadRejectedException {
+// ############ EXCEPTION ######################
+
+exception TTransferRejectedException {
 	1: string reason,
 }
 
@@ -146,13 +267,11 @@ exception TAuthenticationException {
 exception TInvalidTokenException {
 }
 
-exception TImageDataException {
-	1: ImageDataError number,
-	2: string message
+exception TNotFoundException {
 }
 
-exception TDownloadRejectedException {
-	1: UploadError number,
+exception TImageDataException {
+	1: ImageDataError number,
 	2: string message
 }
 
@@ -162,41 +281,77 @@ service SatelliteServer {
 	int getVersion(),
 	
 	// File transfer related
-	TransferInformation requestUpload(1: string userToken, 2: i64 fileSize, 3: list<binary> blockHashes)
-		throws (1:TUploadRejectedException rejection),
-	void cancelUpload(1: string uploadToken),
-	TransferInformation requestDownload(1: string userToken, 2: string imageId),
+	TransferInformation requestImageVersionUpload(1: Token userToken, 2: UUID imageBaseId, 3: i64 fileSize, 4: list<binary> blockHashes)
+		throws (1:TTransferRejectedException rejection, 2:TAuthorizationException authError),
+	void cancelUpload(1: Token uploadToken),
+	UploadStatus queryUploadStatus(1: Token uploadToken)
+		throws (1:TInvalidTokenException ex1),
+
+	TransferInformation requestDownload(1: Token userToken, 2: UUID imageVersionId)
+		throws (1:TAuthorizationException authError),
 	void cancelDownload(1: string downloadToken),
 	
 	// Authentication
-	bool authenticated(1: Token userToken),
-	bool setSessionInvalid(1: Token userToken),
+	bool isAuthenticated(1: Token userToken),
+	void invalidateSession(1: Token userToken),
 	
 	// Misc
     list<OperatingSystem> getOperatingSystems(),
-    list<string> getAllOrganizations(1: Token userToken),
+	list<Virtualizer> getVirtualizers(),
+    list<Organization> getAllOrganizations(),
 	
-	// Image related
-    string finishImageUpload(1: string imageName, 2: string description, 10: bool license, 11: bool internet, 17: int shareMode, 18: string os, 22: Token uploadToken)
-    	throws (1:TUploadFinishException failure),
-    list<ImagePermissionCombined> getImageList(1: Token userToken),
-	ImagePermissionCombined getImageData(1: UUID imageId, 3: Token userToken),
-	bool updateImageData(1: Token userToken, 9: Image image),
+	/*
+	 * Image related
+	 */
+	// Get image list. tagSearch can be null, which disables this type of filtering and returns all
+    list<ImageSummaryRead> getImageList(1: Token userToken, 2: list<string> tagSearch)
+		throws (1:TAuthorizationException authError),
+	// Query detailed information about an image
+	ImageDetailsRead getImageDetails(1: Token userToken, 2: UUID imageBaseId)
+		throws (1:TAuthorizationException authError, 2:TNotFoundException notFound),
+	// Update given image's base meta data
+	bool updateImageBase(1: Token userToken, 2: UUID imageBaseId 3: ImageBaseWrite image)
+		throws (1:TAuthorizationException authError),
+	// Update a certain image version's meta data
+	bool updateImageVersion(1: Token userToken, 2: UUID imageVersionId 3: ImageVersionWrite image)
+		throws (1:TAuthorizationException authError),
+	// Delete given image version. If the version is currently in use by a lecture, it will not be
+	// deleted and false is returned
+	bool deleteImageVersion(1: Token userToken, 2: UUID imageVersionId)
+		throws (1:TAuthorizationException authError, 2:TNotFoundException notFound),
+	// Write list of permissions for given image 
+	bool writeImagePermissions(1: Token userToken, 2: UUID imageId, 3: map<UUID, ImagePermissions> permissions)
+		throws (1:TAuthorizationException authError, 2:TNotFoundException notFound),
+	// Get all user-permissions for given image 
+	map<UUID, ImagePermissions> getImagePermissions(1: Token userToken, 2: UUID imageBaseId)
+		throws (1:TAuthorizationException authError, 2:TNotFoundException notFound),
 	
-	// Lecture related
-    bool writeLecture(1: Token userToken, 2: Lecture lecture),
-    list<Lecture> getLectureList(1: Token userToken),
-	Lecture getLectureData(1: UUID lectureId, 2: Token userToken),
-	bool deleteImage(1: string id, 2: string version, 3: string token),
-	bool connectedToLecture(1: string id, 2: string version, 3: string token),
-	bool deleteLecture(1: string lectureId, 2: string token),
-	bool checkUser(1: string username, 2: string token),
-	bool writeImagePermissions(1: Token userToken, 2: UUID imageId, 3: list<ImagePermission> permissions),
-	bool writeLecturePermissions(1: Token userToken, 2: UUID lectureId, 3: list<LecturePermission> permissions),
-	map<UserID, UserInfo> getImagePermissions(1: Token userToken, 2: UUID imageId),
-	map<UserID, UserInfo> getLecturePermissions(1: Token userToken, 2: UUID lectureId),
-	void deleteAllAdditionalImagePermissions(1: UUID imageID, 2: Token userToken),
-	void deleteAllAdditionalLecturePermissions(1: UUID lectureID, 2: Token userToken),
+	/*
+	 * Lecture related
+	 */
+	// Create new lecture
+    UUID createLecture(1: Token userToken, 2: LectureWrite lecture)
+		throws (1:TAuthorizationException authError),
+	// Update existing lecture
+    bool updateLecture(1: Token userToken, 2: UUID lectureId, 3: LectureWrite lecture)
+		throws (1:TAuthorizationException authError, 2:TNotFoundException notFound),
+	// Get list of all lectures
+    list<LectureSummary> getLectureList(1: Token userToken)
+		throws (1:TAuthorizationException authError),
+	// Get detailed lecture information
+	LectureRead getLectureDetails(1: Token userToken, 2: UUID lectureId)
+		throws (1:TAuthorizationException authError, 2:TNotFoundException notFound),
+	// Get list of lectures that are using the given image version
+	list<LectureSummary> getLecturesByImageVersion(1: Token userToken, 2: UUID imageVersionId)
+		throws (1:TAuthorizationException authError, 2:TNotFoundException notFound),
+	// Delete given lecture
+	bool deleteLecture(1: Token userToken, 2: UUID lectureId)
+		throws (1:TAuthorizationException authError, 2:TNotFoundException notFound),
+	// Write list of permissions for given lecture
+	bool writeLecturePermissions(1: Token userToken, 2: UUID lectureId, 3: map<UUID, LecturePermissions> permissions)
+		throws (1:TAuthorizationException authError, 2:TNotFoundException notFound),
+	map<UUID, LecturePermissions> getLecturePermissions(1: Token userToken, 2: UUID lectureId)
+		throws (1:TAuthorizationException authError, 2:TNotFoundException notFound),
 }
 
 // Central master server
@@ -206,37 +361,55 @@ service MasterServer {
 /*
  * Client (User's Desktop App) calls
  */
+ 	// Ping service
 	bool ping(),
 
-	SessionData authenticate(1:string login, 2:string password) throws (1:AuthenticationException failure),
-	
-	list<OrganizationData> getOrganizations(),
-	
-	list<UserInfo> findUser(1:ID sessionId, 2:string organizationId, 3:string searchTerm) throws (1:AuthorizationException failure),
-	
-	list<ImageData> getPublicImages(1:ID sessionId, 2:i32 page) throws (1:AuthorizationException failure),
-	
-	list<OperatingSystem> getOperatingSystems(),
+	// Old style test-account login 
+	SessionData authenticate(1:string login, 2:string password)
+		throws (1:TAuthorizationException failure),
+	// New style test-account login 
+	ClientSessionData localAccountLogin(1:string login, 2:string password)
+		throws (1:TAuthorizationException failure),
+	// find a user in a given organization by a search term
+	list<UserInfo> findUser(1:Token sessionId, 2:string organizationId, 3:string searchTerm)
+		throws (1:TAuthorizationException failure),
+	// Get list of publicly available images
+	list<ImagePublishData> getPublicImages(1:Token sessionId, 2:i32 page)
+		throws (1:TAuthorizationException failure),
 
 /*
  * Server (Satellite) calls
  */
-	UserInfo getUserFromToken(1:Token token) throws (1:InvalidTokenException failure),
-	
-	bool isServerAuthenticated(1:string serverSessionId),
-	
-	binary startServerAuthentication(1:string organization) throws (1: AuthenticationException failure),
-	
-	ServerSessionData serverAuthenticate(1:string organizationId, 2:binary challengeResponse) throws (1:AuthenticationException failure),
-	
-	UploadData submitImage(1:ID serverSessionId, 2:ImageData imageDescription, 3:list<i32> crcSums) throws (1:AuthorizationException failure, 2: ImageDataException failure2, 3: UploadException failure3),
-	
-	DownloadData getImage(2:ID serverSessionId, 1:UUID uuid) throws (1:AuthorizationException failure, 2: ImageDataException failure2),
-	
-	bool publishUser(1:ID serverSessionId, 2:UserInfo user) throws (1:AuthorizationException failure),
+ 	// Verify a user by querying its meta data from the supplied token
+	UserInfo getUserFromToken(1:Token token)
+		throws (1:TInvalidTokenException failure),
+	// Check if the server is authenticated
+	bool isServerAuthenticated(1:Token serverSessionId),
+	// Start authentication of server for given organization
+	binary startServerAuthentication(1:string organizationId)
+		throws (1: TAuthenticationException failure),
+	// Reply to master server authentication challenge
+	ServerSessionData serverAuthenticate(1:string organizationId, 2:binary challengeResponse)
+		throws (1:TAuthenticationException failure),
+	// Request upload of an image to the master server
+	TransferInformation submitImage(1:Token serverSessionId, 2:ImagePublishData imageDescription, 3:list<binary> blockHashes)
+		throws (1:TAuthorizationException failure, 2: TImageDataException failure2, 3: TTransferRejectedException failure3),
+	// Request download of an image 
+	TransferInformation getImage(2:Token serverSessionId, 1:UUID imageVersionId)
+		throws (1:TAuthorizationException failure, 2: TImageDataException failure2),
 
 	bool registerSatellite(1:string organizationId, 2:string address, 3:string modulus, 4:string exponent),
 
-	bool updateSatelliteAddress(1:ID serverSessionId, 2:string address),
+	bool updateSatelliteAddress(1:Token serverSessionId, 2:string address),
+
+/*
+ * Shared calls
+ */
+ 	// Get list of known organizations with meta data 
+	list<Organization> getOrganizations(),
+
+	list<OperatingSystem> getOperatingSystems(),
+	
+	list<Virtualizer> getVirtualizers(),
 
 }