maddy

 1/*
 2Maddy Mail Server - Composable all-in-one email server.
 3Copyright © 2019-2020 Max Mazurov <fox.cpp@disroot.org>, Maddy Mail Server contributors
 4
 5This program is free software: you can redistribute it and/or modify
 6it under the terms of the GNU General Public License as published by
 7the Free Software Foundation, either version 3 of the License, or
 8(at your option) any later version.
 9
10This program is distributed in the hope that it will be useful,
11but WITHOUT ANY WARRANTY; without even the implied warranty of
12MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13GNU General Public License for more details.
14
15You should have received a copy of the GNU General Public License
16along with this program.  If not, see <https://www.gnu.org/licenses/>.
17*/
18
19// The buffer package provides utilities for temporary storage (buffering)
20// of large blobs.
21package buffer
22
23import (
24	"io"
25)
26
27// Buffer interface represents abstract temporary storage for blobs.
28//
29// The Buffer storage is assumed to be immutable. If any modifications
30// are made - new storage location should be used for them.
31// This is important to ensure goroutine-safety.
32//
33// Since Buffer objects require a careful management of lifetimes, here
34// is the convention: Its always creator responsibility to call Remove after
35// Buffer is no longer used. If Buffer object is passed to a function - it is not
36// guaranteed to be valid after this function returns. If function needs to preserve
37// the storage contents, it should "re-buffer" it either by reading entire blob
38// and storing it somewhere or applying implementation-specific methods (for example,
39// the FileBuffer storage may be "re-buffered" by hard-linking the underlying file).
40type Buffer interface {
41	// Open creates new Reader reading from the underlying storage.
42	Open() (io.ReadCloser, error)
43
44	// Len reports the length of the stored blob.
45	//
46	// Notably, it indicates the amount of bytes that can be read from the
47	// newly created Reader without hiting io.EOF.
48	Len() int
49
50	// Remove discards buffered body and releases all associated resources.
51	//
52	// Multiple Buffer objects may refer to the same underlying storage.
53	// In this case, care should be taken to ensure that Remove is called
54	// only once since it will discard the shared storage and invalidate
55	// all Buffer objects using it.
56	//
57	// Readers previously created using Open can still be used, but
58	// new ones can't be created.
59	Remove() error
60}