epcollect

package
v1.154.2 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

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

View Source
const (
	KeyEndpoint  = "endpoint"
	KeyVersion   = "version"
	KeyValues    = "values"
	KeyFields    = "fields"
	KeySensitive = "sensitive"
	KeySubmitter = "submitter"
)

The keys of a submission's stored payload.

View Source
const EventType = "form_submission"

EventType is the event type of every form submission.

View Source
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

View Source
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.

View Source
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.

View Source
var ErrNoSource = errors.New("this form has no enabled webhook source to store its submissions in; bind it again with manage_script endpoint_set")

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

func Binding(source, field string) string

Binding is what a sensitive field of the form whose source is named source is sealed bound to (#2355).

func FindForm

func FindForm(ctx context.Context, sources SourceLister, form string) (whsource.Source, error)

FindForm is the form source named by its endpoint (as it was bound) or by its source's name.

func PayloadValues

func PayloadValues(payload map[string]any) (values map[string]any, sensitive []string)

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

func (c *Collector) CanSaveFiles() bool

CanSaveFiles reports whether a form's files can be saved here.

func (*Collector) CanSeal

func (c *Collector) CanSeal() bool

CanSeal reports whether a form's sensitive fields can be encrypted here.

func (*Collector) Event

func (c *Collector) Event(sub Submission, source string) (whevent.Event, []byte, error)

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.

func (*Collector) Store

func (c *Collector) Store(ctx context.Context, sub Submission) error

Store writes sub to its form's source and returns once it is durable. Its files are saved first, and removed again when the event is not stored, so a submission that was not stored keeps none of them.

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.

func (*Decrypter) Decrypt

func (d *Decrypter) Decrypt(ctx context.Context, req scripttoken.DecryptRequest) (values map[string]any, opened []string, err error)

Decrypt answers one 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

type SourceLister interface {
	List(ctx context.Context) ([]whsource.Source, error)
}

SourceLister lists the webhook sources (whadmin.Service).

type Sources

type Sources interface {
	FormSource(ctx context.Context, scriptID string) (whsource.Source, bool)
}

Sources finds the source the platform made for a form script.

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

type Submitter

type Submitter struct {
	UserID   string `json:"user_id"`
	Email    string `json:"email"`
	AuthType string `json:"auth_type,omitempty"`
}

Submitter is who sent a submission to a signed-in form.

type Writer

type Writer interface {
	Deliver(ctx context.Context, src whsource.Source, event whevent.Event, body []byte) error
}

Writer makes one event durable in a source (the receiver's Deliver).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL