Parameter value in upload APIs

t-saito · March 27, 2018, 11:04am

Hello everyone,

I have a question about “resumeAt” parameter of “uploadToken.upload” method in case of a media file is uploaded without file chunk.
In https://developer.kaltura.com/workflows/Ingest_and_Upload_Media, sample codes set the “resummeAt” to -1.
On the other hand, in https://blog.kaltura.com/api-inside-out-kaltura-architecture/ and https://github.com/kaltura/webrtc-krecord/blob/master/upload_to_kaltura.php, the sample codes set the “resumeAt” to “null”.
In the PHP and the JavaScript, “null” equals to 0.

Which value should we use for the “resumeAt”?
Or , the value of parameter is not related to the result?

Thank you in advance for your assistance.

Best regards,

jess · March 27, 2018, 11:50am

Hi @t-saito,

resumeAt is only relevant in the event resume is set to true.

To be most strict, if you do not intend to upload in chunks, you best set:

$resume=false;
$finalChunk=true;
$resumeAt=-1;

Same as the defaults here:
https://developer.kaltura.com/workflows/Ingest_and_Upload_Media;step=2

See also the high level explanation above the form, which is taken from the comment here:

github.com

kaltura/server/blob/Mercury-13.17.0/api_v3/services/UploadTokenService.php#L67


		$uploadTokenDb = UploadTokenPeer::retrieveByPK($uploadTokenId);
		if (is_null($uploadTokenDb))
			throw new KalturaAPIException(KalturaErrors::UPLOAD_TOKEN_NOT_FOUND);
			
		$uploadToken = new KalturaUploadToken();
		$uploadToken->fromObject($uploadTokenDb, $this->getResponseProfile());
		return $uploadToken;
	}
	
	/**
	 * Upload a file using the upload token id, returns an error on failure (an exception will be thrown when using one of the Kaltura clients)
	 * Chunks can be uploaded in parallel and they will be appended according to their resumeAt position.
	 * 
	 * A parallel upload session should have three stages:
	 * 1. A single upload with resume=false and finalChunk=false
	 * 2. Parallel upload requests each with resume=true,finalChunk=false and the expected resumetAt position.
	 *    If a chunk fails to upload it can be re-uploaded.
	 * 3. After all of the chunks have been uploaded a final chunk (can be of zero size) should be uploaded 
	 *    with resume=true, finalChunk=true and the expected resumeAt position. In case an UPLOAD_TOKEN_CANNOT_MATCH_EXPECTED_SIZE exception
	 *    has been returned (indicating not all of the chunks were appended yet) the final request can be retried.     
	 *

However, so long as $resume is not set to true, the actual value of $resumeAt does not matter much.
See:

github.com

kaltura/server/blob/Mercury-13.17.0/alpha/apps/kaltura/lib/kUploadTokenMgr.php#L78


	}
	
	/**
	 * Upload a file to the current upload token
	 * @param file $fileData
	 * @param bool $resume
	 * @param bool $finalChunk
	 * @param int $resumeAt
	 * @throw kUploadTokenException
	 */
	public function uploadFileToToken($fileData, $resume = false, $resumeAt = -1)
	{
		$this->_autoFinalize = $this->_uploadToken->getAutoFinalize();
		if($this->_autoFinalize)
			$this->initUploadTokenMemcache();
		
		$allowedStatuses = array(UploadToken::UPLOAD_TOKEN_PENDING, UploadToken::UPLOAD_TOKEN_PARTIAL_UPLOAD);
		if (!in_array($this->_uploadToken->getStatus(), $allowedStatuses, true))
			throw new kUploadTokenException("Invalid upload token status", kUploadTokenException::UPLOAD_TOKEN_INVALID_STATUS);


		$this->updateFileName($fileData);

github.com

kaltura/server/blob/Mercury-13.17.0/alpha/apps/kaltura/lib/kUploadTokenMgr.php#L103


		}
		catch(kUploadTokenException $ex)
		{
			if(!$resume && $this->_finalChunk)
				kFlowHelper::handleUploadFailed($this->_uploadToken);
			
			$this->tryMoveToErrors($fileData);
			throw $ex;
		}
		
		if ($resume)
			$fileSize = $this->handleResume($fileData, $resumeAt);
		else
		{
			$this->handleMoveFile($fileData);
			$fileSize = kFile::fileSize($this->_uploadToken->getUploadTempPath());
		}
		
		if ($this->_finalChunk)
		{
			if (PermissionPeer::isValidForPartner(PermissionName::FEATURE_FILE_TYPE_RESTRICTION_PERMISSION, kCurrentContext::getCurrentPartnerId())

t-saito · March 27, 2018, 12:42pm

Hello @jess,

Thank you for your kind instruction.
It was good to know the behavior of “uploadToken.upload” method.

Sincerely regards