v1

package
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 9, 2022 License: ISC Imports: 1 Imported by: 4

Documentation

Index

Constants

View Source 
const (
	// APIRoute is prefixed onto all routes defined in this package.
	APIRoute = "/comments/v1"

	// RoutePolicy returns the policy for the comments API.
	RoutePolicy = "/policy"

	// RouteNew adds a new comment.
	RouteNew = "/new"

	// RouteEdit edits a comment.
	RouteEdit = "/edit"

	// RouteVote votes on a comment.
	RouteVote = "/vote"

	// RouteDel deletes a comment.
	RouteDel = "/del"

	// RouteCount returns the number of comment on a record.
	RouteCount = "/count"

	// RouteComments returns all comments on a record.
	RouteComments = "/comments"

	// RouteVotes returns all comment votes of a record.
	RouteVotes = "/votes"

	// RouteTimestamps returns the timestamps for the comments of a record.
	RouteTimestamps = "/timestamps"
)
View Source 
const (
	// CountPageSize is the maximum number of tokens that can be
	// included in the Count command.
	//
	// NOTE: This is DEPRECATED and will be deleted as part of the next major
	// release. Use the API's Policy route to retrieve the routes page sizes.
	CountPageSize uint32 = 10
)
View Source 
const (
	// TimestampsPageSize is the maximum number of comment timestamps
	// that can be requests at any one time.
	//
	// NOTE: This is DEPRECATED and will be deleted as part of the next major
	// release. Use the API's Policy route to retrieve the routes page sizes.
	TimestampsPageSize uint32 = 100
)

Variables

View Source 
var (
	// ErrorCodes contains the human readable errors.
	ErrorCodes = map[ErrorCodeT]string{
		ErrorCodeInvalid:            "error invalid",
		ErrorCodeInputInvalid:       "input invalid",
		ErrorCodeUnauthorized:       "unauthorized",
		ErrorCodePublicKeyInvalid:   "public key invalid",
		ErrorCodeSignatureInvalid:   "signature invalid",
		ErrorCodeRecordStateInvalid: "record state invalid",
		ErrorCodeTokenInvalid:       "token invalid",
		ErrorCodeRecordNotFound:     "record not found",
		ErrorCodeRecordLocked:       "record is locked",
		ErrorCodePageSizeExceeded:   "page size exceeded",
		ErrorCodeDuplicatePayload:   "duplicate payload",
	}
)

Functions

This section is empty.

Types

type Comment 

type Comment struct {
	UserID    string       `json:"userid"`    // Unique user ID
	Username  string       `json:"username"`  // Username
	State     RecordStateT `json:"state"`     // Record state
	Token     string       `json:"token"`     // Record token
	ParentID  uint32       `json:"parentid"`  // Parent comment ID if reply
	Comment   string       `json:"comment"`   // Comment text
	PublicKey string       `json:"publickey"` // Public key used for Signature
	Signature string       `json:"signature"` // Client signature
	CommentID uint32       `json:"commentid"` // Comment ID
	Version   uint32       `json:"version"`   // Comment version
	CreatedAt int64        `json:"createdat"` // UNIX timestamp of creation time
	Timestamp int64        `json:"timestamp"` // UNIX timestamp of last edit
	Receipt   string       `json:"receipt"`   // Server sig of client sig
	Downvotes uint64       `json:"downvotes"` // Tolal downvotes on comment
	Upvotes   uint64       `json:"upvotes"`   // Total upvotes on comment

	Deleted bool   `json:"deleted,omitempty"` // Comment has been deleted
	Reason  string `json:"reason,omitempty"`  // Reason for deletion

	// Optional fields to be used freely
	ExtraData     string `json:"extradata,omitempty"`
	ExtraDataHint string `json:"extradatahint,omitempty"`
}

Comment represent a record comment.

A parent ID of 0 indicates that the comment is a base level comment and not a reply commment.

Comments made on a record when it is unvetted and when it is vetted are treated as two distinct groups of comments. When a record becomes vetted the comment ID starts back at 1.

If a comment is deleted the PublicKey, Signature, Receipt, and Timestamp fields will be the from the deletion action, not from the original comment. The only fields that are retained from the original comment are the UserID and Username so that the client can still display the correct user information for the deleted comment. Everything else from the original comment is permanently deleted.

PublicKey is the user's public key that is used to verify the signature.

Signature is the user signature of the: State + Token + ParentID + Comment + ExtraData + ExtraDataHint

Receipt is the server signature of the user signature.

The PublicKey, Signature, and Receipt are all hex encoded and use the ed25519 signature scheme.

type CommentTimestamp 

type CommentTimestamp struct {
	Adds []Timestamp `json:"adds"`
	Del  *Timestamp  `json:"del,omitempty"`
}

CommentTimestamp contains the timestamps for the full history of a single comment.

A CommentAdd is the comments plugin structure that is saved to disk anytime a comment is created or edited. This structure is what will be timestamped. The data payload of a timestamp in the Adds field will contain a JSON encoded CommentAdd. See the politeiad comments plugin API for more details on a CommentAdd.

A CommentDel is the comments plugin structure that is saved to disk anytime a comment is deleted. This structure is what will be timestamped. The data payload of a timestamp in the Del field will contain a JSON encoded CommentDel. See the politeiad comments plugin API for more details on a CommentDel.

type CommentVote 

type CommentVote struct {
	UserID    string       `json:"userid"`    // Unique user ID
	Username  string       `json:"username"`  // Username
	State     RecordStateT `json:"state"`     // Record state
	Token     string       `json:"token"`     // Record token
	CommentID uint32       `json:"commentid"` // Comment ID
	Vote      VoteT        `json:"vote"`      // Upvote or downvote
	PublicKey string       `json:"publickey"` // Public key used for signature
	Signature string       `json:"signature"` // Client signature
	Timestamp int64        `json:"timestamp"` // Received UNIX timestamp
	Receipt   string       `json:"receipt"`   // Server sig of client sig
}

CommentVote represents a comment vote (upvote/downvote).

PublicKey is the user's public key that is used to verify the signature.

Signature is the user signature of the: State + Token + CommentID + Vote

The PublicKey and Signature are hex encoded and use the ed25519 signature scheme.

type Comments 

type Comments struct {
	Token string `json:"token"`
}

Comments requests a record's comments.

type CommentsReply 

type CommentsReply struct {
	Comments []Comment `json:"comments"`
}

CommentsReply is the reply to the comments command.

type Count 

type Count struct {
	Tokens []string `json:"tokens"`
}

Count requests the number of comments on that have been made on the given records. If a record is not found for a token then it will not be included in the returned map.

type CountReply 

type CountReply struct {
	Counts map[string]uint32 `json:"counts"`
}

CountReply is the reply to the count command.

type Del 

type Del struct {
	State     RecordStateT `json:"state"`
	Token     string       `json:"token"`
	CommentID uint32       `json:"commentid"`
	Reason    string       `json:"reason"`
	PublicKey string       `json:"publickey"`
	Signature string       `json:"signature"`
}

Del permanently deletes the provided comment. Only admins can delete comments. A reason must be given for the deletion.

PublicKey is the user's public key that is used to verify the signature.

Signature is the user signature of the: State + Token + CommentID + Reason

The PublicKey and Signature are hex encoded and use the ed25519 signature scheme.

type DelReply 

type DelReply struct {
	Comment Comment `json:"comment"`
}

DelReply is the reply to the Del command.

type Edit added in v1.4.0 

type Edit struct {
	UserID    string       `json:"userid"`    // Unique user ID
	State     RecordStateT `json:"state"`     // Record state
	Token     string       `json:"token"`     // Record token
	ParentID  uint32       `json:"parentid"`  // Parent comment ID
	CommentID uint32       `json:"commentid"` // Comment ID
	Comment   string       `json:"comment"`   // Comment text
	PublicKey string       `json:"publickey"` // Pubkey used for Signature
	Signature string       `json:"signature"` // Client signature

	// Optional fields to be used freely
	ExtraData     string `json:"extradata,omitempty"`
	ExtraDataHint string `json:"extradatahint,omitempty"`
}

Edit edits an existing comment.

PublicKey is the user's public key that is used to verify the signature.

Signature is the user signature of the: State + Token + ParentID + CommentID + Comment + ExtraData + ExtraDataHint

Receipt is the server signature of the user signature.

The PublicKey, Signature, and Receipt are all hex encoded and use the ed25519 signature scheme.

type EditReply added in v1.4.0 

type EditReply struct {
	Comment Comment `json:"comment"`
}

EditReply is the reply to the Edit command.

type ErrorCodeT 

type ErrorCodeT uint32

ErrorCodeT represents a user error code. 

const (
	// ErrorCodeInvalid is an invalid error code.
	ErrorCodeInvalid ErrorCodeT = 0

	// ErrorCodeInputInvalid is returned when there is an error
	// while prasing a command payload.
	ErrorCodeInputInvalid ErrorCodeT = 1

	// ErrorCodeUnauthorized is returned when the user is not authorized.
	ErrorCodeUnauthorized ErrorCodeT = 2

	// ErrorCodePublicKeyInvalid is returned when a public key is
	// invalid.
	ErrorCodePublicKeyInvalid ErrorCodeT = 3

	// ErrorCodeSignatureInvalid is returned when a signature is
	// invalid.
	ErrorCodeSignatureInvalid ErrorCodeT = 4

	// ErrorCodeRecordStateInvalid is returned when the provided state
	// does not match the record state.
	ErrorCodeRecordStateInvalid ErrorCodeT = 5

	// ErrorCodeTokenInvalid is returned when a token is invalid.
	ErrorCodeTokenInvalid ErrorCodeT = 6

	// ErrorCodeRecordNotFound is returned when a record not found.
	ErrorCodeRecordNotFound ErrorCodeT = 7

	// ErrorCodeRecordLocked is returned when a record is locked.
	ErrorCodeRecordLocked ErrorCodeT = 8

	// ErrorCodePageSizeExceeded is returned when the request's page size
	// exceeds the maximum page size of the request.
	ErrorCodePageSizeExceeded ErrorCodeT = 9

	// ErrorCodeDuplicatePayload is returned when a user tries to submit a
	// duplicate payload for the comments plugin, where it tries to write
	// data that already exists. Timestamp data relies on the hash of the
	// payload, therefore duplicate payloads are not allowed since they will
	// cause collisions.
	ErrorCodeDuplicatePayload ErrorCodeT = 10

	// ErrorCodeLast is used by unit tests to verify that all error codes have
	// a human readable entry in the ErrorCodes map. This error will never be
	// returned.
	ErrorCodeLast ErrorCodeT = 11
)

type New 

type New struct {
	State     RecordStateT `json:"state"`
	Token     string       `json:"token"`
	ParentID  uint32       `json:"parentid"`
	Comment   string       `json:"comment"`
	PublicKey string       `json:"publickey"`
	Signature string       `json:"signature"`

	// Optional fields to be used freely
	ExtraData     string `json:"extradata,omitempty"`
	ExtraDataHint string `json:"extradatahint,omitempty"`
}

New creates a new comment.

The parent ID is used to reply to an existing comment. A parent ID of 0 indicates that the comment is a base level comment and not a reply commment.

PublicKey is the user's public key that is used to verify the signature.

Signature is the user signature of the: State + Token + ParentID + Comment + ExtraData + ExtraDataHint

The PublicKey and Signature are hex encoded and use the ed25519 signature scheme.

type NewReply 

type NewReply struct {
	Comment Comment `json:"comment"`
}

NewReply is the reply to the New command.

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.

func (PluginErrorReply) Error 

func (e PluginErrorReply) Error() string

Error satisfies the error interface.

type Policy 

type Policy struct{}

Policy requests the comments API policy.

type PolicyReply 

type PolicyReply struct {
	LengthMax          uint32 `json:"lengthmax"` // In characters
	VoteChangesMax     uint32 `json:"votechangesmax"`
	AllowExtraData     bool   `json:"allowextradata"`
	CountPageSize      uint32 `json:"countpagesize"`
	TimestampsPageSize uint32 `json:"timestampspagesize"`
	VotesPageSize      uint32 `json:"votespagesize"`
	AllowEdits         bool   `json:"allowedits"`
	EditPeriod         uint32 `json:"editperiod"`
}

PolicyReply is the reply to the policy 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 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
)

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 data 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 Timestamps 

type Timestamps struct {
	Token      string   `json:"token"`
	CommentIDs []uint32 `json:"commentids"`
}

Timestamps requests the timestamps for the comments of a record.

type TimestampsReply 

type TimestampsReply struct {
	// map[commentID]CommentTimestamp
	Comments map[uint32]CommentTimestamp `json:"comments"`
}

TimestampsReply is the reply to the Timestamps command.

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.

type Vote 

type Vote struct {
	State     RecordStateT `json:"state"`
	Token     string       `json:"token"`
	CommentID uint32       `json:"commentid"`
	Vote      VoteT        `json:"vote"`
	PublicKey string       `json:"publickey"`
	Signature string       `json:"signature"`
}

Vote casts a comment vote (upvote or downvote). Votes can only be cast on vetted records.

The effect of a new vote on a comment score depends on the previous vote from that user ID. Example, a user upvotes a comment that they have already upvoted, the resulting vote score is 0 due to the second upvote removing the original upvote.

PublicKey is the user's public key that is used to verify the signature.

Signature is the user signature of the: State + Token + CommentID + Vote

The PublicKey and Signature are hex encoded and use the ed25519 signature scheme.

type VoteReply 

type VoteReply struct {
	Downvotes uint64 `json:"downvotes"` // Tolal downvotes on comment
	Upvotes   uint64 `json:"upvotes"`   // Total upvotes on comment
	Timestamp int64  `json:"timestamp"` // Received UNIX timestamp
	Receipt   string `json:"receipt"`   // Server sig of client sig
}

VoteReply is the reply to the Vote command.

type VoteT 

type VoteT int32

VoteT represents a comment upvote/downvote. 

const (
	// VoteInvalid is an invalid comment vote.
	VoteInvalid VoteT = 0

	// VoteDownvote represents a comment downvote.
	VoteDownvote VoteT = -1

	// VoteUpvote represents a comment upvote.
	VoteUpvote VoteT = 1
)

type Votes 

type Votes struct {
	Token  string `json:"token"`
	UserID string `json:"userid,omitempty"`
	Page   uint32 `json:"page,omitempty"`
}

Votes retrieves the record's comment votes that meet the provided filtering criteria. If no filtering criteria is provided then it rerieves all comment votes. This command is paginated, if no page is provided, then the first page is returned. If the requested page does not exist an empty page is returned.

type VotesReply 

type VotesReply struct {
	Votes []CommentVote `json:"votes"`
}

VotesReply is the reply to the Votes command.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.