comments

package
v1.5.0 Latest Latest
Warning

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

 Go to latest Published: Jun 29, 2024 License: ISC Imports: 0 Imported by: 0

Documentation

Overview

Package comments provides a plugin for extending a record with comment functionality.

Index

Constants

View Source 
const (
	// PluginID is the unique identifier for this plugin.
	PluginID = "comments"

	// Plugin commands
	CmdNew        = "new"        // Create a new comment
	CmdEdit       = "edit"       // Edit a comment
	CmdDel        = "del"        // Del a comment
	CmdVote       = "vote"       // Vote on a comment
	CmdGet        = "get"        // Get specified comments
	CmdGetAll     = "getall"     // Get all comments for a record
	CmdGetVersion = "getversion" // Get specified version of a comment
	CmdCount      = "count"      // Get comments count for a record
	CmdVotes      = "votes"      // Get comment votes
	CmdTimestamps = "timestamps" // Get timestamps
)
View Source 
const (
	// SettingKeyCommentLengthMax is the plugin setting key for the
	// SettingCommentLengthMax plugin setting.
	SettingKeyCommentLengthMax = "commentlengthmax"

	// SettingKeyVoteChangesMax is the plugin setting key for the
	// SettingVoteChangesMax plugin setting.
	SettingKeyVoteChangesMax = "votechangesmax"

	// SettingKeyAllowExtraData is the plugin setting key for the
	// SettingAllowExtraData plugin setting.
	SettingKeyAllowExtraData = "allowextradata"

	// SettingKeyVotesPageSize is the plugin setting key for the
	// SettingVotesPageSize plugin setting.
	SettingKeyVotesPageSize = "votespagesize"

	// SettingKeyCountPageSize is the plugin setting key for the
	// SettingCountPageSize plugin setting.
	SettingKeyCountPageSize = "countpagesize"

	// SettingKeyTimestampsPageSize is the plugin setting key for the
	// SettingTimestampsPageSize plugin setting.
	SettingKeyTimestampsPageSize = "timestampspagesize"

	// SettingKeyAllowEdits is the plugin setting key for the
	// SettingAllowEdits plugin setting.
	SettingKeyAllowEdits = "allowedits"

	// SettingKeyEditPeriod is the plugin setting key for the
	// SettingEditPeriod plugin setting.
	SettingKeyEditPeriod = "editperiod"
)

Plugin setting keys can be used to specify custom plugin settings. Default plugin setting values can be overridden by providing a plugin setting key and value to the plugin on startup.

View Source 
const (
	// SettingCommentLengthMax is the default maximum number of
	// characters that are allowed in a comment.
	SettingCommentLengthMax uint32 = 8000

	// SettingVoteChangesMax is the default maximum number of times a
	// user can change their vote on a comment. This prevents a
	// malicious user from being able to spam comment votes.
	SettingVoteChangesMax uint32 = 5

	// SettingAllowExtraData is the default value of the bool flag which
	// determines whether posting extra data along with the comment is allowed.
	SettingAllowExtraData = false

	// SettingVotesPageSize is the default maximum number of comment votes
	// that can be returned at any one time. It defaults to 2500 to limit the
	// comment votes route payload size to be ~1MiB, as each comment vote size
	// is expected to be around 400 bytes which means:
	// 2500 * 400 byte = 1000000 byte = ~1MiB.
	SettingVotesPageSize uint32 = 2500

	// SettingCountPageSize is the default maximum number of comment counts
	// that can be requested at any one time.
	SettingCountPageSize uint32 = 10

	// SettingTimestampsPageSize is the default maximum number of comment
	// timestamps that can be requested at any one time.
	SettingTimestampsPageSize uint32 = 100

	// SettingAllowEdits is the default value of the bool flag which
	// determines whether comment edits are temporarily allowed during the
	// timeframe set by SettingEditPeriod.
	SettingAllowEdits = false

	// SettingEditPeriod is the default maximum amount of time,
	// in seconds, since the submission of a comment where it's still
	// editable. It defaults to five minutes which should be enough time
	// to spot typos and grammar mistakes.
	SettingEditPeriod uint32 = 300
)

Plugin setting default values. These can be overridden by providing a plugin setting key and value to the plugin on startup.

Variables

View Source 
var (
	// ErrorCodes contains the human readable error messages.
	ErrorCodes = map[ErrorCodeT]string{
		ErrorCodeInvalid:                "error code invalid",
		ErrorCodeTokenInvalid:           "token invalid",
		ErrorCodePublicKeyInvalid:       "public key invalid",
		ErrorCodeSignatureInvalid:       "signature invalid",
		ErrorCodeMaxLengthExceeded:      "max length exceeded",
		ErrorCodeNoChanges:              "no changes",
		ErrorCodeCommentNotFound:        "comment not found",
		ErrorCodeUserUnauthorized:       "user unauthorized",
		ErrorCodeParentIDInvalid:        "parent id invalid",
		ErrorCodeVoteInvalid:            "vote invalid",
		ErrorCodeVoteChangesMaxExceeded: "vote changes max exceeded",
		ErrorCodeRecordStateInvalid:     "record state invalid",
		ErrorCodeExtraDataNotAllowed:    "comment extra data not allowed",
		ErrorCodeEditNotAllowed:         "comment edit is not allowed",
		ErrorCodeEmptyComment:           "comment is empty",
	}
)

Functions

This section is empty.

Types

type Comment 

type Comment 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 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 field that is retained from the original comment is the UserID field 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 CommentAdd 

type CommentAdd struct {
	// Data generated by client
	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
	Comment   string       `json:"comment"`   // Comment
	PublicKey string       `json:"publickey"` // Pubkey used for Signature
	Signature string       `json:"signature"` // Client signature

	// Metadata generated by server
	CommentID uint32 `json:"commentid"` // Comment ID
	Version   uint32 `json:"version"`   // Comment version
	Timestamp int64  `json:"timestamp"` // Received UNIX timestamp
	Receipt   string `json:"receipt"`   // Server signature of client signature

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

CommentAdd is the structure that is saved to disk when a comment is created or edited.

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

The structure of the signature field depends on whether the CommentAdd is associated with a new comment or a comment edit:

  1. When a comment is created it's the user signature of the: State + Token + ParentID + Comment + ExtraData + ExtraDataHint.

  2. When a comment is edited it's 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 CommentDel 

type CommentDel struct {
	// Data generated by client
	Token     string       `json:"token"`     // Record token
	State     RecordStateT `json:"state"`     // Record state
	CommentID uint32       `json:"commentid"` // Comment ID
	Reason    string       `json:"reason"`    // Reason for deleting
	PublicKey string       `json:"publickey"` // Pubkey used for Signature
	Signature string       `json:"signature"` // Client signature

	// Metadata generated by server
	ParentID  uint32 `json:"parentid"`  // Parent comment ID
	UserID    string `json:"userid"`    // Author user ID
	Timestamp int64  `json:"timestamp"` // Received UNIX timestamp
	Receipt   string `json:"receipt"`   // Server sig of client sig
}

CommentDel is the structure that is saved to disk when a comment is deleted. Some additional fields like ParentID and UserID are required to be saved since all the CommentAdd records will be deleted and the client needs these additional fields to properly display the deleted comment in the comment hierarchy.

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 CommentTimestamp 

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

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

A CommentAdd is the 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.

A CommentDel is the 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.

A CommentVote is the structure that is saved to disk anytime a comment is voted on. This structure is what will be timestamped. The data payload of a timestamp in the Votes filed will contain a JSON encoded CommentVote.

type CommentVote 

type CommentVote struct {
	// Data generated by client
	UserID    string       `json:"userid"`    // Unique user ID
	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

	// Metadata generated by server
	Timestamp int64  `json:"timestamp"` // Received UNIX timestamp
	Receipt   string `json:"receipt"`   // Server signature of client signature
}

CommentVote is the structure that is saved to disk when a comment is voted on.

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 Count 

type Count struct{}

Count retrieves the comments count for a record. The comments count is the number of comments that have been made on a record.

type CountReply 

type CountReply struct {
	Count uint32 `json:"count"`
}

CountReply is the reply to the Count command.

type Del 

type Del struct {
	State     RecordStateT `json:"state"`     // Record state
	Token     string       `json:"token"`     // Record token
	CommentID uint32       `json:"commentid"` // Comment ID
	Reason    string       `json:"reason"`    // Reason for deletion
	PublicKey string       `json:"publickey"` // Public key used for signature
	Signature string       `json:"signature"` // Client signature
}

Del permanently deletes all versions of the provided comment.

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 

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 

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

EditReply is the reply to the Edit command.

type ErrorCodeT 

type ErrorCodeT uint32

ErrorCodeT represents a error that was caused by the user. 

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

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

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

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

	// ErrorCodeMaxLengthExceeded is returned when a comment exceeds the
	// max length plugin setting.
	ErrorCodeMaxLengthExceeded ErrorCodeT = 4

	// ErrorCodeNoChanges is returned when a comment edit does not
	// contain any changes.
	ErrorCodeNoChanges ErrorCodeT = 5

	// ErrorCodeCommentNotFound is returned when a comment could not be
	// found.
	ErrorCodeCommentNotFound ErrorCodeT = 6

	// ErrorCodeUserUnauthorized is returned when a user is attempting
	// to edit a comment that they did not submit.
	ErrorCodeUserUnauthorized ErrorCodeT = 7

	// ErrorCodeParentIDInvalid is returned when a comment parent ID
	// does not correspond to an actual comment.
	ErrorCodeParentIDInvalid ErrorCodeT = 8

	// ErrorCodeVoteInvalid is returned when a comment vote is invalid.
	ErrorCodeVoteInvalid ErrorCodeT = 9

	// ErrorCodeVoteChangesMaxExceeded is returned when the number of
	// times the user has changed their vote has exceeded the vote
	// changes max plugin setting.
	ErrorCodeVoteChangesMaxExceeded ErrorCodeT = 10

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

	// ErrorCodeExtraDataNotAllowed is returned when comment extra data
	// is found while comment plugin setting does not allow it.
	ErrorCodeExtraDataNotAllowed = 12

	// ErrorCodeEditNotAllowed is returned when comment edit is not
	// allowed.
	ErrorCodeEditNotAllowed = 13

	// ErrorCodeEmptyComment is returned when a comment with no comment text
	// is submitted.
	ErrorCodeEmptyComment = 14

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

type Get 

type Get struct {
	CommentIDs []uint32 `json:"commentids"`
}

Get retrieves a batch of specified comments. The most recent version of each comment is returned. An error is not returned if a comment is not found for one or more of the comment IDs. Those entries will simply not be included in the reply.

type GetAll 

type GetAll struct{}

GetAll retrieves all comments for a record. The latest version of each comment is returned.

type GetAllReply 

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

GetAllReply is the reply to the GetAll command. The returned comments array is ordered by comment ID from smallest to largest.

type GetReply 

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

GetReply is the reply to the Get command. The returned map will not include an entry for any comment IDs that did not correspond to an actual comment. It is the responsibility of the caller to ensure that a comment was returned for all of the provided comment IDs.

type GetVersion 

type GetVersion struct {
	CommentID uint32 `json:"commentid"`
	Version   uint32 `json:"version"`
}

GetVersion retrieves the specified version of a comment.

type GetVersionReply 

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

GetVersionReply is the reply to the GetVersion command.

type New 

type New 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
	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"`
}

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

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 NewReply 

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

NewReply is the reply to the New 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. 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 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 {
	CommentIDs   []uint32 `json:"commentids"`
	IncludeVotes bool     `json:"includevotes,omitempty"`
}

Timestamps retrieves the timestamps for a record's comments. If a requested comment ID does not exist, it will not be included in the reply. An error is not returned.

If IncludeVotes is set to true then the timestamps for the comment votes will also be returned.

type TimestampsReply 

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

TimestampsReply is the reply to the timestamps command.

type Vote 

type Vote struct {
	UserID    string       `json:"userid"`    // Unique user ID
	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
}

Vote casts a comment vote (upvote or downvote).

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. The public key cannot be relied on to remain the same for each user so a user ID must be included.

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 signature of client signature
}

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 {
	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.