cess-oss

README

CESS-OSS ·

CESS-OSS is a service that using REST API specification for accessing CESS cloud storage.

Reporting a Vulnerability

If you find out any system bugs or you have a better suggestions, Please send an email to frode@cess.one, we are happy to communicate with you.

System Requirements

• Linux-amd64

Build from source

Step 1: Install common libraries

Take the ubuntu distribution as an example:

sudo apt update && sudo upgrade
sudo apt install make gcc git curl wget vim util-linux -y

Step 2: Install go locale

CESS-Gateway requires Go1.19 or higher.

See the official Golang installation instructions If you get stuck in the following process.

• Download go1.19 compress the package and extract it to the /use/local directory:

sudo wget -c https://golang.org/dl/go1.19.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local

• You'll need to add /usr/local/go/bin to your path. For most Linux distributions you can run something like:

echo "export PATH=$PATH:/usr/local/go/bin" >> ~/.bashrc && source ~/.bashrc

• View your go version:

go version

Step 3: Build a oss

git clone https://github.com/CESSProject/cess-oss.git
cd cess-oss/
go build -o oss cmd/main.go

If all goes well, you will get a program called oss.

Get started with oss

Step 1: Register a polka wallet

Browser access: App implemented by CESS Explorer, and add an account.

Step 2: Recharge your polka wallet

If you are using the test network, Please join the CESS discord to get it for free. If you are using the official network, please buy CESS tokens.

Step 3: Prepare configuration file

Use oss to generate configuration file templates directly in the current directory:

sudo chmod +x oss
./oss profile

The content of the configuration file template is as follows. You need to fill in your own information into the file. By default, the oss uses conf.toml in the current directory as the runtime configuration file. You can use -c or --config to specify the configuration file Location.

# The rpc address of the chain node
RpcAddr     = ""
# The IP address of the machine's public network used by the scheduler program
ServiceAddr = ""
# Port number monitored by the scheduler program
ServicePort = ""
# Data storage directory
DataDir     = ""
# Phrase or seed of wallet account
AccountSeed = ""

Our testnet rpc address is as follows:
wss://testnet-rpc0.cess.cloud/ws/
wss://testnet-rpc1.cess.cloud/ws/

Step 4: Start the oss service

sudo nohup ./oss run 2>&1 &

Other usage guidelines for oss

Update the oss address

./oss update <ip> <port>

View the oss address

./oss state

Usage for oss API

The public API endpoint URL of CESS-OSS is the server you deploy, All endpoints described in this document should be made relative to this root URL,The following example uses URL instead.

Before using oss, you must authorize it as follows:

1. First register your wallet account: Create an account.

2. Purchase cess storage space:BuySpace

3. Authorize the use right of the space to oss:Authorize

Authentication

The CESS-OSS API uses bearer tokens to authenticate requests.

Your tokens carry many privileges, so be sure to keep them secure! Do not share your secret tokens in publicly accessible locations such as a GitHub repository, client-side code, and so forth.

The bearer token is a cryptic string, usually generated by the server in response to a auth request. The client must send this token in the Authorization header when making requests to protected resources:

Authorization: token

Get token

POST /auth

The authorization interface is used to generate user tokens.

• Request Header

key	value
Content-Type	application/json

• Request Body

field	value
account	your account address
message	custom Signature Message
signature	signature data

Reference for signature calculation method: https://github.com/CESSProject/cess-toolset/tree/main/cess-sign

• Responses

Response schema: application/json

HTTP Code	Message	Description
200	token	returns a token
400	Invalid.Body	body content error
400	InvalidParameter.Account	account error
400	InvalidParameter.Message	message error
400	InvalidParameter.Signature	signature error
403	NoPermission	signature verification failed
500	InternalError	service internal error

• Request example

# curl -X POST URL/auth -d '{"account": "cXgfFb...bjfR", "message": "123456", "signature": [44,30,117,...,109,141]}' -H "Content-Type: application/json"

Create a bucket

PUT /{BucketName}

The put bucket interface is used to create a bucket. When uploading files, the bucket must be specified for storage.

• Request Header

key	value
Authorization	token

• Responses

Response schema: application/json

HTTP Code	Message	Description
200	Block hash	create bucket block hash
400	InvalidHead.MissingToken	token is empty
400	InvalidHead.Token	token error
400	InvalidParameter.Name	wrong bucket name
403	NoPermission	token verification failed
500	InternalError	service internal error

• Request example

# curl -X PUT URL/BucketName -H "Authorization: eyJhbGciOiJIUzI1NiIsI......P0Jrg-hX4bXlIyn5I8ML1g"

Upload a file

PUT /{FileName}

The put file interface is used to upload files to the cess system. You need to submit the file as form data and use provide the specific field. If the upload is successful, you will get the fid of the file.

• Request Header

key	description
Authorization	token
BucketName	stored bucket name

• Request Body

key	value
file	file[binary]

• Responses

Response schema: application/json

HTTP Code	Message	Description
200	fid	file id
400	InvalidHead.MissingToken	token is empty
400	InvalidHead.MissingBucketName	bucketname is empty
400	InvalidHead.BucketName	wrong bucket name
400	InvalidHead.Token	token error
400	Invalid.DuplicateFileName	Duplicate file name
400	Unauthorized	oss is not authorized
400	InvalidParameter.EmptyFile	file is empty
400	InvalidParameter.FormFile	form File
400	InvalidParameter.File	error receiving file
403	NoPermission	token verification failed
500	InternalError	service internal error

• Request example

# curl -X PUT URL/test.log -F 'file=@test.log;type=application/octet-stream' -H "Authorization: eyJhbGciOiJIUzI...Iyn5I8ML1g" -H "BucketName: bucket1"

Download a file

GET /{fid}

The get file interface downloads the file in the CESS storage system according to the fid.

• Request Header

key	value
Operation	download

• Responses

The response schema for the normal return status is: application/octet-stream

The response schema for the exception return status is: application/json, The message returned by the exception is as follows:

HTTP Code	Message	Description
400	InvalidHead.Operation	operation error
403	BackingUp	file is being backed up
404	NotFound	file not found
500	InternalError	service internal error

• Request example

# curl -X GET -o <savefilename> URL/fid -H "Operation: download"

Delete a file

The delete file interface is used for delete a put file.

DELETE /{fid}

• Request Header

key	value
Authorization	token

• Responses

Response schema: application/json

HTTP Code	Message	Description
200	Block hash	delete file block hash
400	InvalidHead.MissToken	token is empty
400	InvalidHead.Token	token error
400	InvalidParameter.Name	fid is error
403	NoPermission	token verification failed
500	InternalError	service internal error

• Request example

# curl -X DELETE URL/fid -H "Authorization: eyJhbGciOiJIUzI1Ni......g-hX4bXlIyn5I8ML1g"

Delete a bucket

The delete bucket interface is used for delete a bucket, all files in the bucket will also be deleted together.

DELETE /{BucketName}

• Request Header

key	value
Authorization	token

• Responses

Response schema: application/json

HTTP Code	Message	Description
200	Block hash	delete bucket block hash
400	InvalidHead.MissToken	token is empty
400	InvalidHead.Token	token error
400	InvalidParameter.Name	bucket name is error
403	NoPermission	token verification failed
500	InternalError	service internal error

• Request example

# curl -X DELETE URL/BucketName -H "Authorization: eyJhbGciOiJIUzI1Ni......g-hX4bXlIyn5I8ML1g"

View bucket info

GET /{BucketName}

This interface is used to view bucket information, including the number of stored files and file IDs.

• Request Header

key	description
Account	account address

• Responses

Response schema: application/json

HTTP Code	Message	Description
200	success	total number of files in bucket and file id
400	InvalidHead.MissingAccount	account is empty
400	InvalidHead.Account	account is error
400	InvalidParameter.Name	bucket name is error
404	NotFound	bucket not found
500	InternalError	service internal error

• Request example

# curl -X GET URL/BucketName -H "Account: cXgfFbnV9H......PMQLoKbjfR"

View bucket list

GET /*

This interface is used to view all buckets.

• Request Header

key	description
Account	account address

• Responses

Response schema: application/json

HTTP Code	Message	Description
200	success	all bucket names
400	InvalidHead.MissingAccount	account is empty
400	InvalidHead.Account	account is error
400	InvalidParameter.Name	* is error
404	NotFound	bucket not found
500	InternalError	service internal error

• Request example

# curl -X GET URL/* -H "Account: cXgfFbnV9H......PMQLoKbjfR"

View file info

GET /{fid}

This interface is used to view the basic information of a file.

• Request Header

key	value
Operation	view

• Responses

Response schema: application/json

HTTP Code	Message	Description
200	success	file information
400	InvalidParameter.Name	fid or operation is error
404	NotFound	file not found
500	InternalError	service internal error

• Request example

# curl -X GET URL/fid -H "Operation: view"

License

Licensed under Apache 2.0