Documentation ¶
Index ¶
- Constants
- Variables
- type CensorshipRecord
- type ErrorCodeT
- type File
- type Inventory
- type InventoryOrdered
- type InventoryOrderedReply
- type InventoryReply
- type MetadataStream
- type Plugin
- type PluginCmd
- type PluginCmdReply
- type PluginErrorReply
- type PluginInventory
- type PluginInventoryReply
- type PluginReads
- type PluginReadsReply
- type PluginSetting
- type PluginWrite
- type PluginWriteReply
- type Proof
- type Record
- type RecordEdit
- type RecordEditMetadata
- type RecordEditMetadataReply
- type RecordEditReply
- type RecordNew
- type RecordNewReply
- type RecordRequest
- type RecordSetStatus
- type RecordSetStatusReply
- type RecordStateT
- type RecordStatusT
- type RecordTimestamps
- type RecordTimestampsReply
- type Records
- type RecordsReply
- type ServerErrorReply
- type Timestamp
- type UserErrorReply
Constants ¶
const ( // APIRoute is prefixed onto all routes in this package. APIRoute = "/v2" // Routes RouteRecordNew = "/recordnew" RouteRecordEdit = "/recordedit" RouteRecordEditMetadata = "/recordeditmetadata" RouteRecordSetStatus = "/recordsetstatus" RouteRecordTimestamps = "/recordtimestamps" RouteRecords = "/records" RouteInventory = "/inventory" RouteInventoryOrdered = "/inventoryordered" RoutePluginWrite = "/pluginwrite" RoutePluginReads = "/pluginreads" RoutePluginInventory = "/plugininventory" // ChallengeSize is the size of a request challenge token in bytes. ChallengeSize = 32 )
const ( // TokenSize is the size of a censorship record token in bytes. TokenSize = 8 // ShortTokenLength is the length, in characters, of a hex encoded // token that has been shortened to improved UX. Short tokens can // be used to retrieve record data but cannot be used on any routes // that write record data. 7 characters was chosen to match the git // abbreviated commitment hash size. ShortTokenLength = 7 )
const ( // InventoryPageSize is the number of tokens that will be returned // per page for all inventory commands. InventoryPageSize uint32 = 20 )
const ( // RecordsPageSize is the maximum number of records that can be // requested using the Records commands. RecordsPageSize uint32 = 5 )
Variables ¶
var ( // ErrorCodes contains the human readable error codes. ErrorCodes = map[ErrorCodeT]string{ ErrorCodeInvalid: "invalid error", ErrorCodeRequestPayloadInvalid: "request payload invalid", ErrorCodeChallengeInvalid: "invalid challenge", ErrorCodeMetadataStreamInvalid: "metadata stream invalid", ErrorCodeMetadataStreamDuplicate: "metadata stream duplicate", ErrorCodeFilesEmpty: "files are empty", ErrorCodeFileNameInvalid: "file name invalid", ErrorCodeFileNameDuplicate: "file name is a duplicate", ErrorCodeFileDigestInvalid: "file digest invalid", ErrorCodeFilePayloadInvalid: "file payload invalid", ErrorCodeFileMIMETypeInvalid: "file mime type invalid", ErrorCodeFileMIMETypeUnsupported: "file mime type not supported", ErrorCodeTokenInvalid: "token invalid", ErrorCodeRecordNotFound: "record not found", ErrorCodeRecordLocked: "record is locked", ErrorCodeNoRecordChanges: "no record changes", ErrorCodeStatusChangeInvalid: "status change invalid", ErrorCodePluginIDInvalid: "pluguin id invalid", ErrorCodePluginCmdInvalid: "plugin cmd invalid", ErrorCodePageSizeExceeded: "page size exceeded", ErrorCodeRecordStateInvalid: "record state invalid", ErrorCodeRecordStatusInvalid: "record status invalid", } )
var ( // RecordStates contains the human readable record states. RecordStates = map[RecordStateT]string{ RecordStateInvalid: "invalid", RecordStateUnvetted: "unvetted", RecordStateVetted: "vetted", } )
var ( // RecordStatuses contains the human readable record statuses. RecordStatuses = map[RecordStatusT]string{ RecordStatusInvalid: "invalid", RecordStatusUnreviewed: "unreviewed", RecordStatusPublic: "public", RecordStatusCensored: "censored", RecordStatusArchived: "archived", } )
Functions ¶
This section is empty.
Types ¶
type CensorshipRecord ¶
type CensorshipRecord struct { // Token is a random censorship token that is generated by the // server. It serves as a unique identifier for the record. Token string `json:"token"` // Merkle is the ordered merkle root of all files in the record. Merkle string `json:"merkle"` // Signature is the server signature of the Merkle+Token. Signature string `json:"signature"` }
CensorshipRecord contains cryptographic proof that a record was accepted for review by the server. The proof is verifiable by the client.
type ErrorCodeT ¶
type ErrorCodeT uint32
ErrorCodeT represents a user error code.
const ( ErrorCodeInvalid ErrorCodeT = 0 ErrorCodeRequestPayloadInvalid ErrorCodeT = 1 ErrorCodeChallengeInvalid ErrorCodeT = 2 ErrorCodeMetadataStreamInvalid ErrorCodeT = 3 ErrorCodeMetadataStreamDuplicate ErrorCodeT = 4 ErrorCodeFilesEmpty ErrorCodeT = 5 ErrorCodeFileNameInvalid ErrorCodeT = 6 ErrorCodeFileNameDuplicate ErrorCodeT = 7 ErrorCodeFileDigestInvalid ErrorCodeT = 8 ErrorCodeFilePayloadInvalid ErrorCodeT = 9 ErrorCodeFileMIMETypeInvalid ErrorCodeT = 10 ErrorCodeFileMIMETypeUnsupported ErrorCodeT = 11 ErrorCodeTokenInvalid ErrorCodeT = 12 ErrorCodeRecordNotFound ErrorCodeT = 13 ErrorCodeRecordLocked ErrorCodeT = 14 ErrorCodeNoRecordChanges ErrorCodeT = 15 ErrorCodeStatusChangeInvalid ErrorCodeT = 16 ErrorCodePluginIDInvalid ErrorCodeT = 17 ErrorCodePluginCmdInvalid ErrorCodeT = 18 ErrorCodePageSizeExceeded ErrorCodeT = 19 ErrorCodeRecordStateInvalid ErrorCodeT = 20 ErrorCodeRecordStatusInvalid ErrorCodeT = 21 ErrorCodeLast ErrorCodeT = 22 )
type File ¶
type File struct { Name string `json:"name"` // Basename of the file MIME string `json:"mime"` // MIME type Digest string `json:"digest"` // SHA256 of decoded Payload Payload string `json:"payload"` // Base64 encoded file payload }
File represents a record file.
type Inventory ¶
type Inventory struct { Challenge string `json:"challenge"` // Random challenge State RecordStateT `json:"state,omitempty"` Status RecordStatusT `json:"status,omitempty"` Page uint32 `json:"page,omitempty"` }
Inventory requests the tokens of the records in the inventory, categorized by record state and record status. The tokens are ordered by the timestamp of their most recent status change, sorted from newest to oldest.
The state, status, and page arguments can be provided to request a specific page of record tokens.
If no status is provided then a page of tokens for all statuses will be returned. All other arguments will be ignored.
type InventoryOrdered ¶
type InventoryOrdered struct { Challenge string `json:"challenge"` // Random challenge State RecordStateT `json:"state"` Page uint32 `json:"page"` }
InventoryOrdered requests a page of record tokens ordered by the timestamp of their most recent status change from newest to oldest. The reply will include tokens for all record statuses.
type InventoryOrderedReply ¶
type InventoryOrderedReply struct { Response string `json:"response"` // Challenge response Tokens []string `json:"tokens"` }
InventoryOrderedReply is the reply to the InventoryOrdered command.
type InventoryReply ¶
type InventoryReply struct { Response string `json:"response"` // Challenge response Unvetted map[string][]string `json:"unvetted"` // [status][]token Vetted map[string][]string `json:"vetted"` // [status][]token }
InventoryReply is the reply to the Inventory command. The map keys are the human readable record statuses defined by the RecordStatuses array.
type MetadataStream ¶
type MetadataStream struct { PluginID string `json:"pluginid"` // Plugin identity StreamID uint32 `json:"streamid"` // Stream identity Payload string `json:"payload"` // JSON encoded metadata }
MetadataStream describes a single metada stream.
type Plugin ¶
type Plugin struct { ID string `json:"id"` Settings []PluginSetting `json:"settings"` }
Plugin describes a plugin and its settings.
type PluginCmd ¶
type PluginCmd struct { Token string `json:"token,omitempty"` // Censorship token ID string `json:"id"` // Plugin identifier Command string `json:"command"` // Plugin command Payload string `json:"payload,omitempty"` // Command payload }
PluginCmd represents plugin command and the command payload. A token is required for all plugin writes, but is optional for reads.
type PluginCmdReply ¶
type PluginCmdReply struct { Token string `json:"token"` // Censorship token ID string `json:"id"` // Plugin identifier Command string `json:"command"` // Plugin command Payload string `json:"payload"` // Response payload // UserError will be populated if a user error is encountered prior // to plugin command execution. UserError *UserErrorReply `json:"usererror,omitempty"` // PluginError will be populated if a plugin error occurred during // plugin command execution. PluginError *PluginErrorReply `json:"pluginerror,omitempty"` }
PluginCmdReply is the reply to an individual plugin command that is part of a batch of plugin commands. The error will be included in the reply if one was encountered.
type PluginErrorReply ¶
type PluginErrorReply struct { PluginID string `json:"pluginid"` ErrorCode uint32 `json:"errorcode"` ErrorContext string `json:"errorcontext,omitempty"` }
PluginErrorReply is the reply that the server returns when it encounters a plugin error. The error code will be specific to the plugin.
func (PluginErrorReply) Error ¶
func (e PluginErrorReply) Error() string
Error satisfies the error interface.
type PluginInventory ¶
type PluginInventory struct {
Challenge string `json:"challenge"` // Random challenge
}
PluginInventory retrieves all active plugins and their settings.
type PluginInventoryReply ¶
type PluginInventoryReply struct { Response string `json:"response"` // Challenge response Plugins []Plugin `json:"plugins"` }
PluginInventoryReply returns all plugins and their settings.
type PluginReads ¶
type PluginReads struct { Challenge string `json:"challenge"` // Random challenge Cmds []PluginCmd `json:"cmds"` }
PluginReads executes a batch of read only plugin commands.
type PluginReadsReply ¶
type PluginReadsReply struct { Response string `json:"response"` // Challenge response Replies []PluginCmdReply `json:"replies"` }
PluginReadsReply is the reply to the PluginReads command.
type PluginSetting ¶
PluginSetting is a structure that holds key/value pairs of a plugin setting.
type PluginWrite ¶
type PluginWrite struct { Challenge string `json:"challenge"` // Random challenge Cmd PluginCmd `json:"cmd"` }
PluginWrite executes a plugin command that writes data.
type PluginWriteReply ¶
type PluginWriteReply struct { Response string `json:"response"` // Challenge response Payload string `json:"payload"` // Response payload }
PluginWriteReply is the reply to the PluginWrite command.
type Proof ¶
type Proof struct { Type string `json:"type"` Digest string `json:"digest"` MerkleRoot string `json:"merkleroot"` MerklePath []string `json:"merklepath"` ExtraData string `json:"extradata"` // JSON encoded }
Proof contains an inclusion proof for the digest in the merkle root. All digests are hex encoded SHA256 digests.
The ExtraData field is used by certain types of proofs to include additional data that is required to validate the proof.
type Record ¶
type Record struct { State RecordStateT `json:"state"` // Record state Status RecordStatusT `json:"status"` // Record status Version uint32 `json:"version"` // Version of this record Timestamp int64 `json:"timestamp"` // Last update Metadata []MetadataStream `json:"metadata"` Files []File `json:"files"` CensorshipRecord CensorshipRecord `json:"censorshiprecord"` }
Record represents a record and all of its contents.
type RecordEdit ¶
type RecordEdit struct { Challenge string `json:"challenge"` // Random challenge Token string `json:"token"` // Censorship token MDAppend []MetadataStream `json:"mdappend,omitempty"` MDOverwrite []MetadataStream `json:"mdoverwrite,omitempty"` FilesAdd []File `json:"filesadd,omitempty"` FilesDel []string `json:"filesdel,omitempty"` }
RecordEdit edits and existing record.
MDAppend appends metadata to a metadata stream. MDOverwrite overwrites a metadata stream. If the metadata stream does not exist yet for either of these arguments, a new metadata stream will be created.
FilesAdd should include files that are being modified or added. FilesDel is the filenames of existing files that will be deleted. If a filename is provided in FilesDel that does not correspond to an actual record file, it will be ignored.
type RecordEditMetadata ¶
type RecordEditMetadata struct { Challenge string `json:"challenge"` // Random challenge Token string `json:"token"` // Censorship token MDAppend []MetadataStream `json:"mdappend,omitempty"` MDOverwrite []MetadataStream `json:"mdoverwrite,omitempty"` }
RecordEditMetadata edits the metadata of a record.
MDAppend appends metadata to a metadata stream. MDOverwrite overwrites a metadata stream. If the metadata stream does not exist yet for either of these arguments, a new metadata stream will be created.
type RecordEditMetadataReply ¶
type RecordEditMetadataReply struct { Response string `json:"response"` // Challenge response Record Record `json:"record"` }
RecordEditMetadataReply is the reply to the RecordEditMetadata command.
type RecordEditReply ¶
type RecordEditReply struct { Response string `json:"response"` // Challenge response Record Record `json:"record"` }
RecordEditReply is the reply to the RecordEdit command.
type RecordNew ¶
type RecordNew struct { Challenge string `json:"challenge"` // Random challenge Metadata []MetadataStream `json:"metadata,omitempty"` Files []File `json:"files"` }
RecordNew creates a new record. It must include all files that are part of the record and it may contain optional metadata.
type RecordNewReply ¶
type RecordNewReply struct { Response string `json:"response"` // Challenge response Record Record `json:"record"` }
RecordNewReply is the reply to the RecordNew command.
type RecordRequest ¶
type RecordRequest struct { Token string `json:"token"` Version uint32 `json:"version,omitempty"` Filenames []string `json:"filenames,omitempty"` OmitAllFiles bool `json:"omitallfiles,omitempty"` }
RecordRequest is used to request a record. It gives the caller granular control over what is returned. The only required field is the token. All other fields are optional. All record files are returned by default unless one of the file arguments is provided.
Version is used to request a specific version of a record. If no version is provided then the most recent version of the record will be returned.
Filenames can be used to request specific files. If filenames is provided then the specified files will be the only files that are returned.
OmitAllFiles can be used to retrieve a record without any of the record files. This supersedes the filenames argument.
type RecordSetStatus ¶
type RecordSetStatus struct { Challenge string `json:"challenge"` // Random challenge Token string `json:"token"` // Censorship token Status RecordStatusT `json:"status"` MDAppend []MetadataStream `json:"mdappend,omitempty"` MDOverwrite []MetadataStream `json:"mdoverwrite,omitempty"` }
RecordSetStatus sets the status of a record.
MDAppend appends metadata to a metadata stream. MDOverwrite overwrites a metadata stream. If the metadata stream does not exist yet for either of these arguments, a new metadata stream will be created.
type RecordSetStatusReply ¶
type RecordSetStatusReply struct { Response string `json:"response"` // Challenge response Record Record `json:"record"` }
RecordSetStatusReply is the reply to the RecordSetStatus command.
type RecordStateT ¶
type RecordStateT uint32
RecordStateT represents the state of a record.
const ( // RecordStateInvalid is an invalid record state. RecordStateInvalid RecordStateT = 0 // RecordStateUnvetted indicates a record has not been made public. RecordStateUnvetted RecordStateT = 1 // RecordStateVetted indicates a record has been made public. RecordStateVetted RecordStateT = 2 // RecordStateLast is used for unit test validation of human readable // errors. RecordStateLast = 3 )
type RecordStatusT ¶
type RecordStatusT uint32
RecordStatusT represents the status of a record.
const ( // RecordStatusInvalid is an invalid status code. RecordStatusInvalid RecordStatusT = 0 // RecordStatusUnreviewed indicates a record has not been made // public yet. The state of an unreviewed record will always be // unvetted. RecordStatusUnreviewed RecordStatusT = 1 // RecordStatusPublic indicates a record has been made public. The // state of a public record will always be vetted. RecordStatusPublic RecordStatusT = 2 // RecordStatusCensored indicates a record has been censored. A // censored record is locked from any further updates and all // record content is permanently deleted. A censored record can // have a state of either unvetted or vetted. RecordStatusCensored RecordStatusT = 3 // RecordStatusArchived indicates a record has been archived. An // archived record is locked from any further updates. An archived // record can have a state of either unvetted or vetted. RecordStatusArchived RecordStatusT = 4 // RecordStatusLast is used for unit test validation of human readable // errors. RecordStatusLast = 5 )
type RecordTimestamps ¶
type RecordTimestamps struct { Challenge string `json:"challenge"` // Random challenge Token string `json:"token"` // Censorship token Version uint32 `json:"version,omitempty"` // Record version }
RecordTimestamps requests the timestamps for a record. If a version is not included the most recent version will be returned.
type RecordTimestampsReply ¶
type RecordTimestampsReply struct { Response string `json:"response"` // Challenge response RecordMetadata Timestamp `json:"recordmetadata"` // map[pluginID]map[streamID]Timestamp Metadata map[string]map[uint32]Timestamp `json:"metadata"` // map[filename]Timestamp Files map[string]Timestamp `json:"files"` }
RecordGetTimestampsReply is the reply ot the RecordTimestamps command.
type Records ¶
type Records struct { Challenge string `json:"challenge"` // Random challenge Requests []RecordRequest `json:"requests"` }
Records retrieves a record. If no version is provided the most recent version will be returned.
type RecordsReply ¶
type RecordsReply struct { Response string `json:"response"` // Challenge response Records map[string]Record `json:"records"` // [token]Record }
RecordsReply is the reply to the Records command. If a record was not found or an error occurred while retrieving it the token will not be included in the returned map.
type ServerErrorReply ¶
type ServerErrorReply struct {
ErrorCode int64 `json:"errorcode"`
}
ServerErrorReply is the reply that the server returns when it encounters an unrecoverable error while executing a command. The HTTP status code will be 500 and the ErrorCode field will contain a UNIX timestamp that the user can provide to the server admin to track down the error details in the logs.
func (ServerErrorReply) Error ¶
func (e ServerErrorReply) Error() string
Error satisfies the error interface.
type Timestamp ¶
type Timestamp struct { Data string `json:"data"` // JSON encoded Digest string `json:"digest"` TxID string `json:"txid"` MerkleRoot string `json:"merkleroot"` Proofs []Proof `json:"proofs"` }
Timestamp contains all of the data required to verify that a piece of record content was timestamped onto the decred blockchain.
All digests are hex encoded SHA256 digests. The merkle root can be found in the OP_RETURN of the specified DCR transaction.
TxID, MerkleRoot, and Proofs will only be populated once the merkle root has been included in a DCR tx and the tx has 6 confirmations. The Data field will not be populated if the data has been censored.
type UserErrorReply ¶
type UserErrorReply struct { ErrorCode ErrorCodeT `json:"errorcode"` ErrorContext string `json:"errorcontext,omitempty"` }
UserErrorReply is the reply that the server returns when it encounters an error that is caused by something that the user did (malformed input, bad timing, etc). The HTTP status code will be 400.
func (UserErrorReply) Error ¶
func (e UserErrorReply) Error() string
Error satisfies the error interface.