Documentation
¶
Overview ¶
Package epcollect stores a form's accepted submissions (#2178): each one becomes one event in the webhook source the platform made for the form, so it lands in webhook_{name} the way any source's events do, with that source's retention. A sensitive field is encrypted here, before the event reaches the receiver's spool, so the spool file, the raw segment, the compacted Parquet and the view all hold its ciphertext (#2179). The submitter is the identity the platform found for the request, never a form field.
Index ¶
- Constants
- Variables
- func Binding(source, field string) string
- func FindForm(ctx context.Context, sources SourceLister, form string) (whsource.Source, error)
- func PayloadValues(payload map[string]any) (values map[string]any, sensitive []string)
- func Reveal(s Sealer, source string, values map[string]any, sensitive []string) (map[string]any, error)
- func RevealStored(s Sealer, source string, values map[string]any, sensitive []string) (map[string]any, error)
- type Collector
- func (c *Collector) CanSaveFiles() bool
- func (c *Collector) CanSeal() bool
- func (c *Collector) Event(sub Submission, source string) (whevent.Event, []byte, error)
- func (c *Collector) Prepare(ctx context.Context, sub *Submission, uploads []epform.Upload) (map[string]string, error)
- func (c *Collector) Store(ctx context.Context, sub Submission) error
- type Decrypter
- type File
- type Files
- type Sealer
- type SourceLister
- type Sources
- type Submission
- type Submitter
- type Writer
Constants ¶
const ( KeyEndpoint = "endpoint" KeyVersion = "version" KeyValues = "values" KeyFields = "fields" KeySensitive = "sensitive" KeySubmitter = "submitter" )
The keys of a submission's stored payload.
const EventType = "form_submission"
EventType is the event type of every form submission.
const SealedUnbound = "[sealed before this release; not readable]"
SealedUnbound stands in the owner's Submissions view for a sensitive value sealed before fields were bound to their form (#2355). It is never decrypted: a value sealed without its form is indistinguishable from any other ciphertext the platform holds, which a row written into the form's table could carry.
Variables ¶
var ErrCannotSaveFiles = errors.New("the form declares file fields, which are saved as managed resources, and this deployment has no managed resources or no webhook receiver to store them through")
ErrCannotSaveFiles is a form declaring a file field where files cannot be saved as managed resources.
var ErrCannotSeal = errors.New("the form declares sensitive fields, which are encrypted when stored, and this deployment has no ENCRYPTION_KEY")
ErrCannotSeal is a form declaring a sensitive field on a deployment that cannot encrypt it.
var ErrNoSource = errors.New("this form has no enabled webhook source to store its submissions in; set its endpoint handler again with manage_script handler_set kind=endpoint")
ErrNoSource is a form whose source this replica cannot find: the form was bound before it defined both handlers, or its source was deleted or disabled.
Functions ¶
func Binding ¶ added in v1.152.2
Binding is what a sensitive field of the form whose source is named source is sealed bound to (#2355).
func FindForm ¶
FindForm is the form source named by its endpoint (as it was bound) or by its source's name.
func PayloadValues ¶
PayloadValues reads a stored submission's payload: its values and the names of its sensitive fields.
func Reveal ¶
func Reveal(s Sealer, source string, values map[string]any, sensitive []string) (map[string]any, error)
Reveal is values with each sensitive field opened: what the form whose source is named source sealed, read back as the value it was. Only a value sealed bound to that form and field opens, so a payload a script assembles opens nothing sealed for anything else (#2355). A field that is not a sealed string is refused, since a sensitive field was never stored any other way.
func RevealStored ¶ added in v1.152.2
func RevealStored(s Sealer, source string, values map[string]any, sensitive []string) (map[string]any, error)
RevealStored is Reveal for rows read from the form's own source: a value sealed before fields were bound reads as SealedUnbound rather than failing the row.
Types ¶
type Collector ¶
type Collector struct {
Sources Sources
Writer Writer
Sealer Sealer
// Files saves a submission's files (#2333); nil saves none, and a form
// with a file field is refused.
Files Files
// MaxFileBytes is the most a saved file may hold
// (resources.managed.max_upload_bytes); zero bounds none here.
MaxFileBytes int64
// Now is the clock a submission is received by; nil is time.Now.
Now func() time.Time
}
Collector stores accepted submissions.
func (*Collector) CanSaveFiles ¶
CanSaveFiles reports whether a form's files can be saved here.
func (*Collector) CanSeal ¶
CanSeal reports whether a form's sensitive fields can be encrypted here.
func (*Collector) Event ¶
Event is the event sub is stored as in the form's source named source, and the payload's JSON: its values with each sensitive one sealed bound to that source and its field, the fields in the order the spec declared them, the sensitive fields' names, and the submitter.
func (*Collector) Prepare ¶
func (c *Collector) Prepare(ctx context.Context, sub *Submission, uploads []epform.Upload) (map[string]string, error)
Prepare readies a submission that carries files before form_submit runs: it names the event the submission will be stored as, and the address each file will be saved at, which it writes into the file's description in sub.Values, so form_submit is handed the address the stored event carries. Nothing is saved: Store saves the files once form_submit accepted. A file name the platform does not store (an extension it refuses) is the field's error.
type Decrypter ¶
type Decrypter struct {
Sources SourceLister
Sealer Sealer
Audit middleware.AuditLogger
}
Decrypter opens a form's sensitive fields for a script run whose persona the form's decrypt_personas names, or the administrator's, and audits each read with the fields it opened (#2179). It answers platform.decrypt.
type File ¶
type File struct {
EventID string
At time.Time
Field string
Name string
ContentType string
Data []byte
}
File is one file of a submission to save (#2333): the event it belongs to and when that was received, the field it was sent in, the name it is saved under, its type and bytes.
type Files ¶
type Files interface {
// FileURI is the address f will be saved at.
FileURI(src whsource.Source, f File) string
// PutFile saves f and says where.
PutFile(ctx context.Context, src whsource.Source, f File) (uri, id string, err error)
// DeleteFile removes a saved file.
DeleteFile(ctx context.Context, id string) error
}
Files saves a form's files as managed resources in its source's library, under the folder the source's attachments are kept in, which is removed with the source.
type Sealer ¶
type Sealer interface {
Enabled() bool
SealBound(binding, plaintext string) (string, error)
OpenBound(binding, sealed string) (string, error)
}
Sealer encrypts a sensitive value (fieldcrypt's RestFieldEncryptor). A value is sealed bound to its form and field and opened only for them (#2355).
type SourceLister ¶
SourceLister lists the webhook sources (whadmin.Service).
type Submission ¶
type Submission struct {
ScriptID string
Endpoint string
Version int
Spec epform.Spec
Values map[string]any
Submitter *Submitter
// EventID and ReceivedAt name the event a submission that carries files
// is stored as, chosen by Prepare so its files' addresses are known
// before form_submit runs; empty, Event chooses them.
EventID string
ReceivedAt time.Time
// Files are the submission's files, saved by Store before its event
// (#2333).
Files []File
}
Submission is one accepted submission: the form, the spec its token carried, the values that passed it, and who sent it (nil on a public form).