syntax = "proto2";
import "steammessages_unified_base.proto";

option py_generic_services = true;

message CCloud_GetUploadServerInfo_Request {
	optional uint32 appid = 1 [(description) = "App ID to which a file will be uploaded to."];
}

message CCloud_GetUploadServerInfo_Response {
	optional string server_url = 1;
}

message CCloud_BeginHTTPUpload_Request {
	optional uint32 appid = 1 [(description) = "App ID for which the file is being uploaded."];
	optional uint32 file_size = 2 [(description) = "Original file size in bytes."];
	optional string filename = 3 [(description) = "Name of the file to store in the cloud."];
	optional string file_sha = 4 [(description) = "Hex string (40 digits) representing the SHA1 digest of the file."];
	optional bool is_public = 5 [(description) = "True if the file should be marked public on the UFS, false otherwise."];
	repeated string platforms_to_sync = 6 [(description) = "Array of string specifying which platforms to sync; value values: all, windows, osx, linux."];
	repeated string request_headers_names = 7 [(description) = "Names for headers you'll want to set on your upload request. May be left blank."];
	repeated string request_headers_values = 8 [(description) = "Values for headers you'll want to set on your upload request. The number of names must equal the number of values."];
}

message CCloud_BeginHTTPUpload_Response {
	message HTTPHeaders {
		optional string name = 1;
		optional string value = 2;
	}

	optional fixed64 ugcid = 1 [(description) = "UGC ID of the uploaded file."];
	optional fixed32 timestamp = 2 [(description) = "Server timestamp of file."];
	optional string url_host = 3 [(description) = "Host name of server to which file should be uploaded via HTTP PUT."];
	optional string url_path = 4 [(description) = "Relative path on server to which file should be uploaded."];
	optional bool use_https = 5 [(description) = "If true, use https, otherwise use http."];
	repeated .CCloud_BeginHTTPUpload_Response.HTTPHeaders request_headers = 6 [(description) = "Name-value pairs to be sent in HTTP PUT request."];
}

message CCloud_CommitHTTPUpload_Request {
	optional bool transfer_succeeded = 1 [(description) = "True if the HTTP PUT to the upload URL succeeded (URL provided in response to Cloud.BeginHTTPUpload), false if a failure occurred."];
	optional uint32 appid = 2 [(description) = "App ID for which the file is being uploaded. Must match the app ID provided to Cloud.BeginHTTPUpload."];
	optional string file_sha = 3 [(description) = "Hex string (40 digits) representing the SHA1 digest of the file. Must match the SHA1 digest provided to Cloud.BeginHTTPUpload."];
	optional string filename = 4 [(description) = "Filename as specified in the Cloud.BeginHTTPUpload request."];
}

message CCloud_CommitHTTPUpload_Response {
	optional bool file_committed = 1 [(description) = "True if the file was successfully committed, false otherwise."];
}

message CCloud_GetFileDetails_Request {
	optional uint64 ugcid = 1 [(description) = "ID of the Cloud file to get details for."];
	optional uint32 appid = 2 [(description) = "App ID the file belongs to."];
}

message CCloud_UserFile {
	optional uint32 appid = 1;
	optional uint64 ugcid = 2;
	optional string filename = 3;
	optional uint64 timestamp = 4;
	optional uint32 file_size = 5;
	optional string url = 6;
	optional fixed64 steamid_creator = 7;
}

message CCloud_GetFileDetails_Response {
	optional .CCloud_UserFile details = 1;
}

message CCloud_EnumerateUserFiles_Request {
	optional uint32 appid = 1 [(description) = "App ID to enumerate the files of."];
	optional bool extended_details = 2 [(description) = "(Optional) Get extended details back on the files found. Defaults to only returned the app Id and UGC Id of the files found."];
	optional uint32 count = 3 [(description) = "(Optional) Maximum number of results to return on this call. Defaults to a maximum of 500 files returned."];
	optional uint32 start_index = 4 [(description) = "(Optional) Starting index to begin enumeration at. Defaults to the beginning of the list."];
}

message CCloud_EnumerateUserFiles_Response {
	repeated .CCloud_UserFile files = 1;
	optional uint32 total_files = 2;
}

message CCloud_Delete_Request {
	optional string filename = 1;
	optional uint32 appid = 2 [(description) = "App ID the file belongs to."];
}

message CCloud_Delete_Response {
}

message CCloud_GetClientEncryptionKey_Request {
}

message CCloud_GetClientEncryptionKey_Response {
	optional bytes key = 1 [(description) = "AES-256 encryption key"];
	optional int32 crc = 2 [(description) = "CRC of key"];
}

message CCloud_CDNReport_Notification {
	optional fixed64 steamid = 1;
	optional string url = 2;
	optional bool success = 3;
	optional uint32 http_status_code = 4;
	optional uint64 expected_bytes = 5;
	optional uint64 received_bytes = 6;
	optional uint32 duration = 7;
}

message CCloud_ExternalStorageTransferReport_Notification {
	optional string host = 1;
	optional string path = 2;
	optional bool is_upload = 3;
	optional bool success = 4;
	optional uint32 http_status_code = 5;
	optional uint64 bytes_expected = 6;
	optional uint64 bytes_actual = 7;
	optional uint32 duration_ms = 8;
	optional uint32 cellid = 9;
}

message CCloud_ClientBeginFileUpload_Request {
	optional uint32 appid = 1 [(description) = "App ID for which the file is being uploaded."];
	optional uint32 file_size = 2 [(description) = "file size as transmitted and stored in Cloud."];
	optional uint32 raw_file_size = 3 [(description) = "file size before any compression and/or encryption."];
	optional bytes file_sha = 4 [(description) = "SHA-1 of raw file."];
	optional uint64 time_stamp = 5 [(description) = "Timestamp of file."];
	optional string filename = 6 [(description) = "Name of the file to store in the cloud."];
	optional uint32 platforms_to_sync = 7 [default = 4294967295];
	optional uint32 cell_id = 9 [(description) = "Client's cell ID so we can pick storage location."];
	optional bool can_encrypt = 10 [(description) = "if true, client can encrypt the file before uploading it"];
	optional bool is_shared_file = 11 [(description) = "if true, this is going to be UGC or a screenshot or some other shared file"];
}

message ClientCloudFileUploadBlockDetails {
	message HTTPHeaders {
		optional string name = 1;
		optional string value = 2;
	}

	optional string url_host = 1 [(description) = "Host name of server to which file should be uploaded via HTTP PUT."];
	optional string url_path = 2 [(description) = "Relative path on server to which file should be uploaded."];
	optional bool use_https = 3 [(description) = "If true, use https, otherwise use http."];
	optional int32 http_method = 4 [(description) = "EHTTPMethod to use for this block."];
	repeated .ClientCloudFileUploadBlockDetails.HTTPHeaders request_headers = 5 [(description) = "Name-value pairs to be sent in HTTP PUT request."];
	optional uint64 block_offset = 6 [(description) = "offset of file block to upload"];
	optional uint32 block_length = 7 [(description) = "length of file block to upload - if zero, no part of the file is part of this block"];
	optional bytes explicit_body_data = 8 [(description) = "explicit body data to use, instead of file data, for this block"];
	optional bool may_parallelize = 9 [(description) = "if true, this request may be done in parallel with other similarly-marked requests"];
}

message CCloud_ClientBeginFileUpload_Response {
	optional bool encrypt_file = 1 [(description) = "If true, the file should be encrypted by the client before upload"];
	repeated .ClientCloudFileUploadBlockDetails block_requests = 2 [(description) = "HTTP requests to make to perform upload"];
}

message CCloud_ClientCommitFileUpload_Request {
	optional bool transfer_succeeded = 1 [(description) = "True if all block uploads succeeded, false if any of them failed."];
	optional uint32 appid = 2 [(description) = "App ID for which the file is being uploaded. Must match the app ID provided to Cloud.BeginFileUpload."];
	optional bytes file_sha = 3 [(description) = "SHA1 digest of the raw file. Must match the SHA1 digest provided to Cloud.BeginFileUpload."];
	optional string filename = 4 [(description) = "Filename as specified in the Cloud.BeginFileUpload request."];
}

message CCloud_ClientCommitFileUpload_Response {
	optional bool file_committed = 1 [(description) = "True if the file was successfully committed, false otherwise."];
}

message CCloud_ClientFileDownload_Request {
	optional uint32 appid = 1 [(description) = "App ID the file is part of."];
	optional string filename = 2 [(description) = "Filename of the file."];
}

message CCloud_ClientFileDownload_Response {
	message HTTPHeaders {
		optional string name = 1;
		optional string value = 2;
	}

	optional uint32 appid = 1 [(description) = "Application the file belongs to"];
	optional uint32 file_size = 2 [(description) = "file size as transmitted and stored in the Cloud"];
	optional uint32 raw_file_size = 3 [(description) = "file size when decompressed and/or decrypted"];
	optional bytes sha_file = 4 [(description) = "SHA of file"];
	optional uint64 time_stamp = 5 [(description) = "Timestamp of file"];
	optional bool is_explicit_delete = 6 [(description) = "True if this is an explicitly deleted file"];
	optional string url_host = 7 [(description) = "Host to GET the file from"];
	optional string url_path = 8 [(description) = "Path on that host to use, including URL parameters if any"];
	optional bool use_https = 9 [(description) = "If set, use HTTPS, else use HTTP"];
	repeated .CCloud_ClientFileDownload_Response.HTTPHeaders request_headers = 10 [(description) = "Name-value pairs to be sent in HTTP GET request."];
	optional bool encrypted = 11;
}

message CCloud_ClientDeleteFile_Request {
	optional uint32 appid = 1 [(description) = "App ID for which the file is being deleted."];
	optional string filename = 2 [(description) = "Filename of file."];
	optional bool is_explicit_delete = 3 [(description) = "If true, this is a 'delete'; if false, it is a 'forget'"];
}

message CCloud_ClientDeleteFile_Response {
}

message CCloud_ClientConflictResolution_Notification {
	optional uint32 appid = 1 [(description) = "App ID for which the conflict was resolved."];
	optional bool chose_local_files = 2 [(description) = "Did the user choose to keep the files local to the machine they are on right now?"];
}

service Cloud {
	option (service_description) = "A service for Steam Cloud operations.";
	rpc GetUploadServerInfo (.CCloud_GetUploadServerInfo_Request) returns (.CCloud_GetUploadServerInfo_Response) {
		option (method_description) = "Returns the URL of the proper cloud server for a user.";
	}
	rpc BeginHTTPUpload (.CCloud_BeginHTTPUpload_Request) returns (.CCloud_BeginHTTPUpload_Response) {
		option (method_description) = "Begins the process of uploading a file to Steam external storage services. File should be uploaded via HTTP PUT to the returned URL, after which the upload must be finalized by a call to CommitHTTPUpload.";
	}
	rpc CommitHTTPUpload (.CCloud_CommitHTTPUpload_Request) returns (.CCloud_CommitHTTPUpload_Response) {
		option (method_description) = "Commits a file upload initiated by BeginHTTPUpload and transferred via HTTP PUT.";
	}
	rpc GetFileDetails (.CCloud_GetFileDetails_Request) returns (.CCloud_GetFileDetails_Response) {
		option (method_description) = "Returns details on a Cloud file.";
	}
	rpc EnumerateUserFiles (.CCloud_EnumerateUserFiles_Request) returns (.CCloud_EnumerateUserFiles_Response) {
		option (method_description) = "Enumerates Cloud files for a user of a given app ID. Returns up to 500 files at a time.";
	}
	rpc Delete (.CCloud_Delete_Request) returns (.CCloud_Delete_Response) {
		option (method_description) = "Deletes a file from the user's cloud.";
	}
	rpc GetClientEncryptionKey (.CCloud_GetClientEncryptionKey_Request) returns (.CCloud_GetClientEncryptionKey_Response) {
		option (method_description) = "Gets the user's Cloud file encryption key.";
	}
	rpc CDNReport (.CCloud_CDNReport_Notification) returns (.NoResponse) {
		option (method_description) = "Reports the result of a CDN transfer.";
	}
	rpc ExternalStorageTransferReport (.CCloud_ExternalStorageTransferReport_Notification) returns (.NoResponse) {
		option (method_description) = "Reports the result of an external Cloud storage transfer.";
	}
	rpc ClientBeginFileUpload (.CCloud_ClientBeginFileUpload_Request) returns (.CCloud_ClientBeginFileUpload_Response) {
		option (method_description) = "Initiate an upload to Cloud.";
	}
	rpc ClientCommitFileUpload (.CCloud_ClientCommitFileUpload_Request) returns (.CCloud_ClientCommitFileUpload_Response) {
		option (method_description) = "Commit the file upload or indicate failure.";
	}
	rpc ClientFileDownload (.CCloud_ClientFileDownload_Request) returns (.CCloud_ClientFileDownload_Response) {
		option (method_description) = "Initiate a file download.";
	}
	rpc ClientDeleteFile (.CCloud_ClientDeleteFile_Request) returns (.CCloud_ClientDeleteFile_Response) {
		option (method_description) = "Delete or forget a file.";
	}
	rpc ClientConflictResolution (.CCloud_ClientConflictResolution_Notification) returns (.NoResponse) {
		option (method_description) = "User has picked a resolution for a Cloud conflict.";
	}
}