Object store

The objects plugin stores binary payloads in the database file and names them in a tree of files and directories. Enable it at open with plugins {objects {}}. It has no settings. See plugin selection for the open options. Calls without it report the unavailable status.

The typed wrappers use plugin_call or plugin_stream with plugin objects. Request members use lowerCamelCase, such as expectedRevision.

Payloads

A payload is an immutable byte sequence. Its digest is the SHA-256 of all its bytes. Write a payload through an upload stream: write appends bytes in order and finish publishes the payload atomically. Equal bytes publish one payload: a second finish of the same bytes reports deduplicated true and stores nothing new. The database splits payloads into content-defined chunks of 256 KiB to 4 MiB, so edits to a large payload share most chunks with earlier versions. manifest lists the chunks, and an open stream reads any byte range: seek moves its position and read copies from it.

Published payloads are never deleted. Removing a file or pointing it at another payload keeps the earlier payload, and history keeps every earlier version of the file. An upload that does not finish publishes nothing. Closing the stream abandons it, and the next open removes what an interrupted upload left behind.

Each upload holds a working buffer of up to 4 MiB from the database memory budget until it finishes or closes. An upload that cannot fit reports out_of_memory. Calls on one stream are serialized; separate streams can run at the same time.

Digests cross the API as 64 hexadecimal digits in either case. Results show them as {#sha256 <hex>} values.

Files and directories

Every node lives under the root directory, entity 0. A directory holds named children; a file names one published payload. Names are non-empty UTF-8 text without / or NUL, and are not . or ... Names are unique within a directory and hold at most 4096 bytes.

A record describes one node:

Member	Value
`entity`	The node's entity.
`parent`	The parent directory's entity, `0` for the root.
`name`	The node's name in its parent.
`kind`	`file` or `directory`.
`revision`	The transaction that last changed the node.
`size`	A file's payload size in bytes.
`digest`	A file's payload digest.

create creates up to 4096 nodes in one commit. A node names its parent by entity, or with under by the position of an earlier directory in the same request:

TRON

219 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	5C 6E6F746573	txt "notes"
0F	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
19	7C 23736861323536	txt "#sha256"
21	14 40 393565383464 6133386362656664 6633663966366566 3032323031303734 6337333132346637 6366323032356433 6531643639653539 3161343130383536 6662	txt "95e84da38cbefdf3f9f6ef02…"
63	0F 0A 19000000 2100 0000	map leaf, size 10: @19 → @21
6D	5C 756E646572	txt "under"
73	02 01000000000000 00	i64 1
7C	0F 0A 6D000000 7300 0000	map leaf, size 10: @6D → @73
86	6C 646967657374	txt "digest"
8D	0F 0A 86000000 6300 0000	map leaf, size 10: @86 → @63
97	4C 6E616D65	txt "name"
9C	9C 68656C6C6F2E74 7874	txt "hello.txt"
A6	0F 0A 97000000 9C00 0000	map leaf, size 10: @97 → @9C
B0	07 12 04820000 7C00 0000 8D000000 A600 0000	map branch, size 18, depth 0 (root), slots 2, 9, 15: @7C → @8D → @A6
C2	0E 11 00 0300 020000 00 0F000000 B00000 00	array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @F → @B0
D3	C2000000 00000000	root → @C2; previous: none

A file can name only a published payload. A merge patch can also write stardust/object/digest on an entity; the commit then needs a published payload too.

Revisions

Each write commits atomically through the commit queue. A refused write changes nothing. update, move and remove take an expected revision. Pass the revision of a record you read to refuse the write when another writer changed the node since: the call reports conflict. Pass 0 to skip the check. An update to the current payload, or a move to the current name and parent, changes nothing and keeps the revision.

With replace true, a move can replace a destination node of the same kind. A file replaces a file. A directory replaces only an empty directory. Remove deletes a file or an empty directory.

Reads

Every tree read uses one snapshot of the database. Concurrent writes do not change a read in progress. children lists a directory in name order. path returns the names from the root to a node. files finds the files that hold a payload. A stream read verifies every chunk it reads against its digest and reports evaluation_failed when stored bytes do not match.

Without the plugin

On a database that does not enable objects, a write that sets stardust/object/digest fails with the unavailable status and the code plugin_required. Payloads and files that the plugin stored stay in the database file and return when the plugin is enabled again.

Operations

Operation	Returns	Summary
Objects.Get	document	objects.get(entity) returns the owned record document of an object file or directory.
Objects.Lookup	document	objects.lookup(parent, name) returns the owned record document of a directory's child.
Objects.Children	document	objects.children(parent) returns an owned array document of a directory's child records in name order.
Objects.Path	document	objects.path(entity) returns an owned array document of the names from the root to an object node.
Objects.Files	document	objects.files(digest) returns an owned ascending array document of the file entities that hold a payload.
Objects.Manifest	document	objects.manifest(digest) returns a published payload's owned manifest document.
Objects.Create	document	objects.create(nodes) creates files and directories in one commit and returns an owned array document of their records.
Objects.Update	document	objects.update(entity, digest, expected_revision) points a file at another published payload and returns its owned record document.
Objects.Move	document	objects.move(entity, parent, name, expected_revision, replace) renames or moves a node and returns its owned record document.
Objects.Remove	none	objects.remove(entity, expected_revision) removes a file or an empty directory.
Objects.Upload	plugin_stream	objects.upload() opens an owned plugin stream that uploads one payload.
Objects.Open	plugin_stream	objects.open(digest) opens an owned plugin stream that reads a published payload.

Objects.Get

53 B

func (v Objects) Get(entity int64) (*Document, error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`entity`	`int64`	Value	Required	The node's entity.

Errors

Status	When
`StatusInvalidArgument`	entity is not a user entity
`StatusNotFound`	no object node has the entity
`StatusEvaluationFailed`	stored tree metadata or the manifest of a named payload is corrupted
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

Read the record of a file

640 B

upload, err := db.Objects().Upload()
if err != nil {
	return err
}
defer upload.Close()
if _, err := upload.Write([]byte("Hello, objects")); err != nil {
	return err
}
published, err := upload.Finish()
if err != nil {
	return err
}
defer published.Close()

nodes, err := stardust.Parse([]byte(`[{name hello.txt digest {#sha256 "95e84da38cbefdf3f9f6ef02201074c73124f7cf2025d3e1d69e591a410856fb"}}]`), stardust.DUST)
if err != nil {
	return err
}
defer nodes.Close()
created, err := db.Objects().Create(nodes)
if err != nil {
	return err
}
created.Close()

result, err := db.Objects().Get(1)
if err != nil {
	return err
}
defer result.Close()

TRON

316 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	7C 23736861323536	txt "#sha256"
00C	14 40 393565383464 6133386362656664 6633663966366566 3032323031303734 6337333132346637 6366323032356433 6531643639653539 3161343130383536 6662	txt "95e84da38cbefdf3f9f6ef02…"
04E	0F 0A 04000000 0C00 0000	map leaf, size 10: @4 → @C
058	6C 656E74697479	txt "entity"
05F	02 01000000000000 00	i64 1
068	0F 0A 58000000 5F00 0000	map leaf, size 10: @58 → @5F
072	4C 6B696E64	txt "kind"
077	4C 66696C65	txt "file"
07C	0F 0A 72000000 7700 0000	map leaf, size 10: @72 → @77
086	4C 73697A65	txt "size"
08B	02 0E000000000000 00	i64 14
094	0F 0A 86000000 8B00 0000	map leaf, size 10: @86 → @8B
09E	8C 7265766973696F 6E	txt "revision"
0A7	02 02000000000000 00	i64 2
0B0	0F 0A 9E000000 A700 0000	map leaf, size 10: @9E → @A7
0BA	6C 706172656E74	txt "parent"
0C1	02 00000000000000 00	i64 0
0CA	0F 0A BA000000 C100 0000	map leaf, size 10: @BA → @C1
0D4	07 0E 00120000 B000 0000 CA000000	map branch, size 14, depth 2, slots 9, 12: @B0 → @CA
0E2	07 0E 04010000 9400 0000 D4000000	map branch, size 14, depth 1, slots 2, 8: @94 → @D4
0F0	6C 646967657374	txt "digest"
0F7	0F 0A F0000000 4E00 0000	map leaf, size 10: @F0 → @4E
101	4C 6E616D65	txt "name"
106	9C 68656C6C6F2E74 7874	txt "hello.txt"
110	0F 0A 01010000 0601 0000	map leaf, size 10: @101 → @106
11A	07 1A 30830000 6800 0000 7C000000 E200 0000 F7000000 1001 0000	map branch, size 26, depth 0 (root), slots 4, 5, 8, 9, 15: @68 → @7C → @E2 → @F7 → @110
134	1A010000 00000000	root → @11A; previous: none

C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

Objects.Lookup

69 B

func (v Objects) Lookup(parent int64, name string) (*Document, error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`parent`	`int64`	Value	Required	The directory's entity. 0 selects the root.
`name`	`string`	Value	Required	The child's name.

Errors

Status	When
`StatusInvalidArgument`	the parent or the name is invalid, or the parent is a file
`StatusNotFound`	the parent has no child with the name, or the parent does not exist
`StatusEvaluationFailed`	stored tree metadata or the manifest of a named payload is corrupted
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

Find a child of the root by name

342 B

nodes, err := stardust.Parse([]byte(`[{name notes}]`), stardust.DUST)
if err != nil {
	return err
}
defer nodes.Close()
created, err := db.Objects().Create(nodes)
if err != nil {
	return err
}
created.Close()

// Entity 0 is the root directory.
result, err := db.Objects().Lookup(0, "notes")
if err != nil {
	return err
}
defer result.Close()

TRON

184 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 656E74697479	txt "entity"
0B	02 01000000000000 00	i64 1
14	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
1E	4C 6B696E64	txt "kind"
23	9C 6469726563746F 7279	txt "directory"
2D	0F 0A 1E000000 2300 0000	map leaf, size 10: @1E → @23
37	8C 7265766973696F 6E	txt "revision"
40	02 02000000000000 00	i64 2
49	0F 0A 37000000 4000 0000	map leaf, size 10: @37 → @40
53	6C 706172656E74	txt "parent"
5A	02 00000000000000 00	i64 0
63	0F 0A 53000000 5A00 0000	map leaf, size 10: @53 → @5A
6D	07 0E 00120000 4900 0000 63000000	map branch, size 14, depth 2, slots 9, 12: @49 → @63
7B	07 0A 00010000 6D00 0000	map branch, size 10, depth 1, slots 8: @6D
85	4C 6E616D65	txt "name"
8A	5C 6E6F746573	txt "notes"
90	0F 0A 85000000 8A00 0000	map leaf, size 10: @85 → @8A
9A	07 16 30810000 1400 0000 2D000000 7B00 0000 90000000	map branch, size 22, depth 0 (root), slots 4, 5, 8, 15: @14 → @2D → @7B → @90
B0	9A000000 00000000	root → @9A; previous: none

C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

Objects.Children

58 B

func (v Objects) Children(parent int64) (*Document, error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`parent`	`int64`	Value	Required	The directory's entity. 0 selects the root.

Errors

Status	When
`StatusInvalidArgument`	the parent is invalid or is a file
`StatusNotFound`	the parent does not exist
`StatusEvaluationFailed`	stored tree metadata or the manifest of a named payload is corrupted
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

List the root directory

314 B

nodes, err := stardust.Parse([]byte(`[{name notes} {name drafts}]`), stardust.DUST)
if err != nil {
	return err
}
defer nodes.Close()
created, err := db.Objects().Create(nodes)
if err != nil {
	return err
}
created.Close()

result, err := db.Objects().Children(0)
if err != nil {
	return err
}
defer result.Close()

TRON

374 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	6C 656E74697479	txt "entity"
00B	02 02000000000000 00	i64 2
014	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
01E	4C 6B696E64	txt "kind"
023	9C 6469726563746F 7279	txt "directory"
02D	0F 0A 1E000000 2300 0000	map leaf, size 10: @1E → @23
037	8C 7265766973696F 6E	txt "revision"
040	02 03000000000000 00	i64 3
049	0F 0A 37000000 4000 0000	map leaf, size 10: @37 → @40
053	6C 706172656E74	txt "parent"
05A	02 00000000000000 00	i64 0
063	0F 0A 53000000 5A00 0000	map leaf, size 10: @53 → @5A
06D	07 0E 00120000 4900 0000 63000000	map branch, size 14, depth 2, slots 9, 12: @49 → @63
07B	07 0A 00010000 6D00 0000	map branch, size 10, depth 1, slots 8: @6D
085	4C 6E616D65	txt "name"
08A	6C 647261667473	txt "drafts"
091	0F 0A 85000000 8A00 0000	map leaf, size 10: @85 → @8A
09B	07 16 30810000 1400 0000 2D000000 7B00 0000 91000000	map branch, size 22, depth 0 (root), slots 4, 5, 8, 15: @14 → @2D → @7B → @91
0B1	6C 656E74697479	txt "entity"
0B8	02 01000000000000 00	i64 1
0C1	0F 0A B1000000 B800 0000	map leaf, size 10: @B1 → @B8
0CB	4C 6B696E64	txt "kind"
0D0	9C 6469726563746F 7279	txt "directory"
0DA	0F 0A CB000000 D000 0000	map leaf, size 10: @CB → @D0
0E4	8C 7265766973696F 6E	txt "revision"
0ED	02 03000000000000 00	i64 3
0F6	0F 0A E4000000 ED00 0000	map leaf, size 10: @E4 → @ED
100	6C 706172656E74	txt "parent"
107	02 00000000000000 00	i64 0
110	0F 0A 00010000 0701 0000	map leaf, size 10: @100 → @107
11A	07 0E 00120000 F600 0000 10010000	map branch, size 14, depth 2, slots 9, 12: @F6 → @110
128	07 0A 00010000 1A01 0000	map branch, size 10, depth 1, slots 8: @11A
132	4C 6E616D65	txt "name"
137	5C 6E6F746573	txt "notes"
13D	0F 0A 32010000 3701 0000	map leaf, size 10: @132 → @137
147	07 16 30810000 C100 0000 DA000000 2801 0000 3D010000	map branch, size 22, depth 0 (root), slots 4, 5, 8, 15: @C1 → @DA → @128 → @13D
15D	0E 11 00 0300 020000 00 9B000000 470100 00	array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @9B → @147
16E	5D010000 00000000	root → @15D; previous: none

C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

Objects.Path

54 B

func (v Objects) Path(entity int64) (*Document, error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`entity`	`int64`	Value	Required	The node's entity. 0 selects the root, whose path is empty.

Errors

Status	When
`StatusInvalidArgument`	entity is not a user entity
`StatusNotFound`	the node or one of its ancestors does not exist
`StatusEvaluationFailed`	stored tree metadata or the manifest of a named payload is corrupted
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

Read the path of a nested directory

318 B

nodes, err := stardust.Parse([]byte(`[{name notes} {name drafts under 1}]`), stardust.DUST)
if err != nil {
	return err
}
defer nodes.Close()
created, err := db.Objects().Create(nodes)
if err != nil {
	return err
}
created.Close()

result, err := db.Objects().Path(2)
if err != nil {
	return err
}
defer result.Close()

TRON

42 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 6E6F746573	txt "notes"
0A	6C 647261667473	txt "drafts"
11	0E 11 00 0300 020000 00 04000000 0A0000 00	array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @4 → @A
22	11000000 00000000	root → @11; previous: none

C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

Objects.Files

56 B

func (v Objects) Files(digest string) (*Document, error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`digest`	`string`	Value	Required	The payload's SHA-256 digest as 64 hexadecimal digits.

Errors

Status	When
`StatusInvalidArgument`	the digest is not 64 hexadecimal digits
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

Find the files that hold a payload

800 B

upload, err := db.Objects().Upload()
if err != nil {
	return err
}
defer upload.Close()
if _, err := upload.Write([]byte("Hello, objects")); err != nil {
	return err
}
published, err := upload.Finish()
if err != nil {
	return err
}
defer published.Close()

nodes, err := stardust.Parse([]byte(`[{name a.txt digest {#sha256 "95e84da38cbefdf3f9f6ef02201074c73124f7cf2025d3e1d69e591a410856fb"}} {name b.txt digest {#sha256 "95e84da38cbefdf3f9f6ef02201074c73124f7cf2025d3e1d69e591a410856fb"}}]`), stardust.DUST)
if err != nil {
	return err
}
defer nodes.Close()
created, err := db.Objects().Create(nodes)
if err != nil {
	return err
}
created.Close()

result, err := db.Objects().Files("95e84da38cbefdf3f9f6ef02201074c73124f7cf2025d3e1d69e591a410856fb")
if err != nil {
	return err
}
defer result.Close()

TRON

47 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 01000000000000 00	i64 1
0D	02 02000000000000 00	i64 2
16	0E 11 00 0300 020000 00 04000000 0D0000 00	array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @4 → @D
27	16000000 00000000	root → @16; previous: none

C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

Objects.Manifest

59 B

func (v Objects) Manifest(digest string) (*Document, error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`digest`	`string`	Value	Required	The payload's SHA-256 digest as 64 hexadecimal digits.

Errors

Status	When
`StatusInvalidArgument`	the digest is not 64 hexadecimal digits
`StatusNotFound`	no payload with the digest is published
`StatusEvaluationFailed`	the stored manifest is corrupted
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Notes

The manifest is {digest size chunks}. chunks lists {digest size} in byte order and is omitted for an empty payload.

Examples

Read the manifest of a published payload

412 B

upload, err := db.Objects().Upload()
if err != nil {
	return err
}
defer upload.Close()
if _, err := upload.Write([]byte("Hello, objects")); err != nil {
	return err
}
published, err := upload.Finish()
if err != nil {
	return err
}
defer published.Close()

result, err := db.Objects().Manifest("95e84da38cbefdf3f9f6ef02201074c73124f7cf2025d3e1d69e591a410856fb")
if err != nil {
	return err
}
defer result.Close()

TRON

324 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	7C 23736861323536	txt "#sha256"
00C	14 40 393565383464 6133386362656664 6633663966366566 3032323031303734 6337333132346637 6366323032356433 6531643639653539 3161343130383536 6662	txt "95e84da38cbefdf3f9f6ef02…"
04E	0F 0A 04000000 0C00 0000	map leaf, size 10: @4 → @C
058	7C 23736861323536	txt "#sha256"
060	14 40 393565383464 6133386362656664 6633663966366566 3032323031303734 6337333132346637 6366323032356433 6531643639653539 3161343130383536 6662	txt "95e84da38cbefdf3f9f6ef02…"
0A2	0F 0A 58000000 6000 0000	map leaf, size 10: @58 → @60
0AC	4C 73697A65	txt "size"
0B1	02 0E000000000000 00	i64 14
0BA	0F 0A AC000000 B100 0000	map leaf, size 10: @AC → @B1
0C4	6C 646967657374	txt "digest"
0CB	0F 0A C4000000 A200 0000	map leaf, size 10: @C4 → @A2
0D5	07 0E 00030000 BA00 0000 CB000000	map branch, size 14, depth 0 (root), slots 8, 9: @BA → @CB
0E3	0E 0D 00 0100 010000 00 D5000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @D5
0F0	4C 73697A65	txt "size"
0F5	02 0E000000000000 00	i64 14
0FE	0F 0A F0000000 F500 0000	map leaf, size 10: @F0 → @F5
108	6C 646967657374	txt "digest"
10F	0F 0A 08010000 4E00 0000	map leaf, size 10: @108 → @4E
119	6C 6368756E6B73	txt "chunks"
120	0F 0A 19010000 E300 0000	map leaf, size 10: @119 → @E3
12A	07 12 00070000 FE00 0000 0F010000 2001 0000	map branch, size 18, depth 0 (root), slots 8, 9, 10: @FE → @10F → @120
13C	2A010000 00000000	root → @12A; previous: none

C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

Objects.Create

59 B

func (v Objects) Create(nodes *Document) (*Document, error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`nodes`	`*Document`	Borrowed for the call	Required	A borrowed array of at most 4096 nodes. Each has name, and parent (entity, default 0) or under (one-based position of an earlier directory). A file also has digest {#sha256 hex}. Without digest, the node is a directory.

Errors

Status	When
`StatusInvalidArgument`	the array is empty or malformed, a name is invalid, or a parent is a file
`StatusNotFound`	a parent does not exist or a digest is not published
`StatusConflict`	a name is already taken in its parent or appears twice, or the database holds writes
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Notes

Nodes are created in order. A node names its parent by entity, or by the one-based position of an earlier directory in the same array with under.

Examples

Create a directory and a file in one commit

641 B

upload, err := db.Objects().Upload()
if err != nil {
	return err
}
defer upload.Close()
if _, err := upload.Write([]byte("Hello, objects")); err != nil {
	return err
}
published, err := upload.Finish()
if err != nil {
	return err
}
defer published.Close()

// under 1 places hello.txt in the first node of the request.
nodes, err := stardust.Parse([]byte(`[{name notes} {name hello.txt under 1 digest {#sha256 "95e84da38cbefdf3f9f6ef02201074c73124f7cf2025d3e1d69e591a410856fb"}}]`), stardust.DUST)
if err != nil {
	return err
}
defer nodes.Close()

result, err := db.Objects().Create(nodes)
if err != nil {
	return err
}
defer result.Close()

TRON

505 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	6C 656E74697479	txt "entity"
00B	02 01000000000000 00	i64 1
014	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
01E	4C 6B696E64	txt "kind"
023	9C 6469726563746F 7279	txt "directory"
02D	0F 0A 1E000000 2300 0000	map leaf, size 10: @1E → @23
037	8C 7265766973696F 6E	txt "revision"
040	02 03000000000000 00	i64 3
049	0F 0A 37000000 4000 0000	map leaf, size 10: @37 → @40
053	6C 706172656E74	txt "parent"
05A	02 00000000000000 00	i64 0
063	0F 0A 53000000 5A00 0000	map leaf, size 10: @53 → @5A
06D	07 0E 00120000 4900 0000 63000000	map branch, size 14, depth 2, slots 9, 12: @49 → @63
07B	07 0A 00010000 6D00 0000	map branch, size 10, depth 1, slots 8: @6D
085	4C 6E616D65	txt "name"
08A	5C 6E6F746573	txt "notes"
090	0F 0A 85000000 8A00 0000	map leaf, size 10: @85 → @8A
09A	07 16 30810000 1400 0000 2D000000 7B00 0000 90000000	map branch, size 22, depth 0 (root), slots 4, 5, 8, 15: @14 → @2D → @7B → @90
0B0	7C 23736861323536	txt "#sha256"
0B8	14 40 393565383464 6133386362656664 6633663966366566 3032323031303734 6337333132346637 6366323032356433 6531643639653539 3161343130383536 6662	txt "95e84da38cbefdf3f9f6ef02…"
0FA	0F 0A B0000000 B800 0000	map leaf, size 10: @B0 → @B8
104	6C 656E74697479	txt "entity"
10B	02 02000000000000 00	i64 2
114	0F 0A 04010000 0B01 0000	map leaf, size 10: @104 → @10B
11E	4C 6B696E64	txt "kind"
123	4C 66696C65	txt "file"
128	0F 0A 1E010000 2301 0000	map leaf, size 10: @11E → @123
132	4C 73697A65	txt "size"
137	02 0E000000000000 00	i64 14
140	0F 0A 32010000 3701 0000	map leaf, size 10: @132 → @137
14A	8C 7265766973696F 6E	txt "revision"
153	02 03000000000000 00	i64 3
15C	0F 0A 4A010000 5301 0000	map leaf, size 10: @14A → @153
166	6C 706172656E74	txt "parent"
16D	02 01000000000000 00	i64 1
176	0F 0A 66010000 6D01 0000	map leaf, size 10: @166 → @16D
180	07 0E 00120000 5C01 0000 76010000	map branch, size 14, depth 2, slots 9, 12: @15C → @176
18E	07 0E 04010000 4001 0000 80010000	map branch, size 14, depth 1, slots 2, 8: @140 → @180
19C	6C 646967657374	txt "digest"
1A3	0F 0A 9C010000 FA00 0000	map leaf, size 10: @19C → @FA
1AD	4C 6E616D65	txt "name"
1B2	9C 68656C6C6F2E74 7874	txt "hello.txt"
1BC	0F 0A AD010000 B201 0000	map leaf, size 10: @1AD → @1B2
1C6	07 1A 30830000 1401 0000 28010000 8E01 0000 A3010000 BC01 0000	map branch, size 26, depth 0 (root), slots 4, 5, 8, 9, 15: @114 → @128 → @18E → @1A3 → @1BC
1E0	0E 11 00 0300 020000 00 9A000000 C60100 00	array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @9A → @1C6
1F1	E0010000 00000000	root → @1E0; previous: none

C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

Objects.Update

95 B

func (v Objects) Update(entity int64, digest string, expectedRevision int64) (*Document, error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`entity`	`int64`	Value	Required	The file's entity.
`digest`	`string`	Value	Required	The payload's SHA-256 digest as 64 hexadecimal digits.
`expectedRevision`	`int64`	Value	Required	The transaction that last touched the node, from its record. 0 skips the check.

Errors

Status	When
`StatusInvalidArgument`	the entity is a directory or invalid, the digest is malformed, or `expected_revision` is negative
`StatusNotFound`	the file does not exist or the digest is not published
`StatusConflict`	`expected_revision` is stale, or the database holds writes
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

Point a file at a new payload

870 B

for _, text := range []string{"Hello, objects", "Revised notes"} {
	upload, err := db.Objects().Upload()
	if err != nil {
		return err
	}
	if _, err := upload.Write([]byte(text)); err != nil {
		upload.Close()
		return err
	}
	published, err := upload.Finish()
	upload.Close()
	if err != nil {
		return err
	}
	published.Close()
}

nodes, err := stardust.Parse([]byte(`[{name hello.txt digest {#sha256 "95e84da38cbefdf3f9f6ef02201074c73124f7cf2025d3e1d69e591a410856fb"}}]`), stardust.DUST)
if err != nil {
	return err
}
defer nodes.Close()
created, err := db.Objects().Create(nodes)
if err != nil {
	return err
}
created.Close()

// 0 skips the revision check; pass a record's revision to refuse a stale write.
result, err := db.Objects().Update(1, "2b6d3a4299dac5900171112d4fd569b48e54711d8937f6ff5ca00528d47afad2", 0)
if err != nil {
	return err
}
defer result.Close()

TRON

316 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	7C 23736861323536	txt "#sha256"
00C	14 40 326236643361 3432393964616335 3930303137313131 3264346664353639 6234386535343731 3164383933376636 6666356361303035 3238643437616661 6432	txt "2b6d3a4299dac5900171112d…"
04E	0F 0A 04000000 0C00 0000	map leaf, size 10: @4 → @C
058	6C 656E74697479	txt "entity"
05F	02 01000000000000 00	i64 1
068	0F 0A 58000000 5F00 0000	map leaf, size 10: @58 → @5F
072	4C 6B696E64	txt "kind"
077	4C 66696C65	txt "file"
07C	0F 0A 72000000 7700 0000	map leaf, size 10: @72 → @77
086	4C 73697A65	txt "size"
08B	02 0D000000000000 00	i64 13
094	0F 0A 86000000 8B00 0000	map leaf, size 10: @86 → @8B
09E	8C 7265766973696F 6E	txt "revision"
0A7	02 03000000000000 00	i64 3
0B0	0F 0A 9E000000 A700 0000	map leaf, size 10: @9E → @A7
0BA	6C 706172656E74	txt "parent"
0C1	02 00000000000000 00	i64 0
0CA	0F 0A BA000000 C100 0000	map leaf, size 10: @BA → @C1
0D4	07 0E 00120000 B000 0000 CA000000	map branch, size 14, depth 2, slots 9, 12: @B0 → @CA
0E2	07 0E 04010000 9400 0000 D4000000	map branch, size 14, depth 1, slots 2, 8: @94 → @D4
0F0	6C 646967657374	txt "digest"
0F7	0F 0A F0000000 4E00 0000	map leaf, size 10: @F0 → @4E
101	4C 6E616D65	txt "name"
106	9C 68656C6C6F2E74 7874	txt "hello.txt"
110	0F 0A 01010000 0601 0000	map leaf, size 10: @101 → @106
11A	07 1A 30830000 6800 0000 7C000000 E200 0000 F7000000 1001 0000	map branch, size 26, depth 0 (root), slots 4, 5, 8, 9, 15: @68 → @7C → @E2 → @F7 → @110
134	1A010000 00000000	root → @11A; previous: none

C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

Objects.Move

119 B

func (v Objects) Move(entity int64, parent int64, name string, expectedRevision int64, replace bool) (*Document, error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`entity`	`int64`	Value	Required	The node to move.
`parent`	`int64`	Value	Required	The destination directory. 0 selects the root.
`name`	`string`	Value	Required	The node's new name.
`expectedRevision`	`int64`	Value	Required	The transaction that last touched the node, from its record. 0 skips the check.
`replace`	`bool`	Value	Required	Replace an existing node of the same kind at the destination. False reports conflict for an occupied name.

Errors

Status	When
`StatusInvalidArgument`	the request is malformed, the destination is a file or inside the node, the kinds differ, or a replaced directory is not empty
`StatusNotFound`	the node or the destination does not exist
`StatusConflict`	the name is occupied without replace, `expected_revision` is stale, or the database holds writes
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Notes

With replace, a node of the same kind at the destination is replaced; a directory only when it is empty. A move into the node's own subtree is invalid.

Examples

Move a directory into another

396 B

nodes, err := stardust.Parse([]byte(`[{name notes} {name drafts}]`), stardust.DUST)
if err != nil {
	return err
}
defer nodes.Close()
created, err := db.Objects().Create(nodes)
if err != nil {
	return err
}
created.Close()

// false refuses to replace a node that already has the name.
result, err := db.Objects().Move(2, 1, "archive", 0, false)
if err != nil {
	return err
}
defer result.Close()

TRON

186 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 656E74697479	txt "entity"
0B	02 02000000000000 00	i64 2
14	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
1E	4C 6B696E64	txt "kind"
23	9C 6469726563746F 7279	txt "directory"
2D	0F 0A 1E000000 2300 0000	map leaf, size 10: @1E → @23
37	8C 7265766973696F 6E	txt "revision"
40	02 04000000000000 00	i64 4
49	0F 0A 37000000 4000 0000	map leaf, size 10: @37 → @40
53	6C 706172656E74	txt "parent"
5A	02 01000000000000 00	i64 1
63	0F 0A 53000000 5A00 0000	map leaf, size 10: @53 → @5A
6D	07 0E 00120000 4900 0000 63000000	map branch, size 14, depth 2, slots 9, 12: @49 → @63
7B	07 0A 00010000 6D00 0000	map branch, size 10, depth 1, slots 8: @6D
85	4C 6E616D65	txt "name"
8A	7C 61726368697665	txt "archive"
92	0F 0A 85000000 8A00 0000	map leaf, size 10: @85 → @8A
9C	07 16 30810000 1400 0000 2D000000 7B00 0000 92000000	map branch, size 22, depth 0 (root), slots 4, 5, 8, 15: @14 → @2D → @7B → @92
B2	9C000000 00000000	root → @9C; previous: none

C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

Objects.Remove

67 B

func (v Objects) Remove(entity int64, expectedRevision int64) error

Parameters

Parameter	Type	Ownership	Default	Meaning
`entity`	`int64`	Value	Required	The node to remove.
`expectedRevision`	`int64`	Value	Required	The transaction that last touched the node, from its record. 0 skips the check.

Errors

Status	When
`StatusInvalidArgument`	the entity is invalid, the directory is not empty, or `expected_revision` is negative
`StatusNotFound`	the node does not exist
`StatusConflict`	`expected_revision` is stale, or the database holds writes
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Notes

The payload stays published.

Examples

Remove an empty directory

274 B

nodes, err := stardust.Parse([]byte(`[{name drafts}]`), stardust.DUST)
if err != nil {
	return err
}
defer nodes.Close()
created, err := db.Objects().Create(nodes)
if err != nil {
	return err
}
created.Close()

if err := db.Objects().Remove(1, 0); err != nil {
	return err
}

C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

Objects.Upload

48 B

func (v Objects) Upload() (*PluginStream, error)

Errors

Status	When
`StatusUnavailable`	the database does not enable the objects plugin
`StatusConflict`	the database holds writes
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Notes

The stream holds a working buffer of up to 4 MiB from the database memory budget until it finishes or closes. Write appends bytes; finish publishes the payload and returns {digest size deduplicated}.

Examples

Upload a payload and publish it

388 B

upload, err := db.Objects().Upload()
if err != nil {
	return err
}
// Close abandons the upload unless it finished.
defer upload.Close()

// The upload stream implements io.Writer, so io.Copy can stream into it.
if _, err := io.Copy(upload, strings.NewReader("Hello, objects")); err != nil {
	return err
}

result, err := upload.Finish()
if err != nil {
	return err
}
defer result.Close()

TRON

189 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	7C 23736861323536	txt "#sha256"
0C	14 40 393565383464 6133386362656664 6633663966366566 3032323031303734 6337333132346637 6366323032356433 6531643639653539 3161343130383536 6662	txt "95e84da38cbefdf3f9f6ef02…"
4E	0F 0A 04000000 0C00 0000	map leaf, size 10: @4 → @C
58	4C 73697A65	txt "size"
5D	02 0E000000000000 00	i64 14
66	0F 0A 58000000 5D00 0000	map leaf, size 10: @58 → @5D
70	6C 646967657374	txt "digest"
77	0F 0A 70000000 4E00 0000	map leaf, size 10: @70 → @4E
81	CC 64656475706C69 6361746564	txt "deduplicated"
8E	01	bit false
8F	0F 0A 81000000 8E00 0000	map leaf, size 10: @81 → @8E
99	07 0E 00440000 7700 0000 8F000000	map branch, size 14, depth 1, slots 10, 14: @77 → @8F
A7	07 0E 00030000 6600 0000 99000000	map branch, size 14, depth 0 (root), slots 8, 9: @66 → @99
B5	A7000000 00000000	root → @A7; previous: none

C exports: stardust_db_plugin_stream_open, stardust_result_error, stardust_result_release

Objects.Open

59 B

func (v Objects) Open(digest string) (*PluginStream, error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`digest`	`string`	Value	Required	The payload's SHA-256 digest as 64 hexadecimal digits.

Errors

Status	When
`StatusInvalidArgument`	the digest is not 64 hexadecimal digits
`StatusNotFound`	no payload with the digest is published
`StatusEvaluationFailed`	the stored manifest is corrupted
`StatusUnavailable`	the database does not enable the objects plugin
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

upload, err := db.Objects().Upload()
if err != nil {
	return err
}
defer upload.Close()
if _, err := upload.Write([]byte("Hello, objects")); err != nil {
	return err
}
published, err := upload.Finish()
if err != nil {
	return err
}
defer published.Close()

reader, err := db.Objects().Open("95e84da38cbefdf3f9f6ef02201074c73124f7cf2025d3e1d69e591a410856fb")
if err != nil {
	return err
}
defer reader.Close()
// The reader is an io.ReadSeeker and an io.ReaderAt.
if _, err := reader.Seek(7, io.SeekStart); err != nil {
	return err
}
data := make([]byte, 7)
read, err := io.ReadFull(reader, data)
if err != nil {
	return err
}
// data holds "objects".
result := int64(read)

TRON

21 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 07000000000000 00	i64 7
0D	04000000 00000000	root → @4; previous: none

C exports: stardust_db_plugin_stream_open, stardust_result_error, stardust_result_release