danabra.mov
An experimental TypeSpec syntax for Lexicon
meh
+10
SYNTAX.md
+10
SYNTAX.md
···
1570
1570
// → input: { encoding: "application/octet-stream", schema: bytes }
1571
1571
```
1572
1572
1573
+
**Input encoding (no schema):**
1574
+
```typespec
1575
+
@procedure
1576
+
op importRepo(
1577
+
@encoding("application/vnd.ipld.car")
1578
+
input: void
1579
+
): void;
1580
+
// → input: { encoding: "application/vnd.ipld.car" } (no schema)
1581
+
```
1582
+
1573
1583
**Output encoding:**
1574
1584
```typespec
1575
1585
@query
+3
packages/emitter/lib/main.tsp
+3
packages/emitter/lib/main.tsp
+13
packages/emitter/src/decorators.ts
+13
packages/emitter/src/decorators.ts
···
17
17
const errorModelKey = Symbol("errorModel");
18
18
const encodingKey = Symbol("encoding");
19
19
const inlineKey = Symbol("inline");
20
+
const bytesMaxLengthKey = Symbol("bytesMaxLength");
21
+
22
+
/**
23
+
* @bytesMaxLength decorator for maximum length of bytes type
24
+
*/
25
+
export function $bytesMaxLength(context: DecoratorContext, target: Type, value: Type) {
26
+
const numValue = (value as any).kind === "Number" || (value as any).kind === "Numeric" ? (value as any).value : value;
27
+
context.program.stateMap(bytesMaxLengthKey).set(target, Number(numValue));
28
+
}
29
+
30
+
export function getBytesMaxLength(program: Program, target: Type): number | undefined {
31
+
return program.stateMap(bytesMaxLengthKey).get(target);
32
+
}
20
33
21
34
/**
22
35
* @encoding decorator for custom output/input encoding
+62
-9
packages/emitter/src/emitter.ts
+62
-9
packages/emitter/src/emitter.ts
···
46
46
isErrorModel,
47
47
getEncoding,
48
48
isInline,
49
+
getBytesMaxLength,
49
50
} from "./decorators.js";
50
51
51
52
export interface EmitterOptions {
···
66
67
"language",
67
68
"atIdentifier",
68
69
"bytes",
70
+
"cidLink",
69
71
]);
70
72
71
73
const FORMAT_MAP: Record<string, string> = {
···
232
234
}
233
235
234
236
private createLexicon(id: string, ns: any): LexiconDocument {
235
-
const lexicon: LexiconDocument = { lexicon: 1, id, defs: {} };
236
237
const description = getDoc(this.program, ns);
237
-
if (description) lexicon.description = description;
238
+
const lexicon: LexiconDocument = description
239
+
? { lexicon: 1, id, description, defs: {} }
240
+
: { lexicon: 1, id, defs: {} };
238
241
return lexicon;
239
242
}
240
243
···
729
732
}
730
733
731
734
private addInput(def: any, param: any) {
732
-
const inputSchema = this.typeToLexiconDefinition(param.type);
733
-
if (inputSchema) {
734
-
const encoding = getEncoding(this.program, param) || "application/json";
735
-
def.input = { encoding, schema: inputSchema };
735
+
const encoding = getEncoding(this.program, param);
736
+
if (param.type?.kind !== "Intrinsic") {
737
+
const inputSchema = this.typeToLexiconDefinition(param.type);
738
+
if (inputSchema) {
739
+
def.input = { encoding: encoding || "application/json", schema: inputSchema };
740
+
}
741
+
} else if (encoding) {
742
+
def.input = { encoding };
736
743
}
737
744
}
738
745
···
936
943
scalar: Scalar,
937
944
prop?: ModelProperty,
938
945
): LexiconDefinition | null {
939
-
// Special case: bytes type
940
-
if (scalar.name === "bytes") {
941
-
return { type: "bytes" };
946
+
// Check if this scalar (or its base) is bytes type
947
+
const isBytes = this.isScalarBytes(scalar);
948
+
949
+
if (isBytes) {
950
+
const byteDef: any = { type: "bytes" };
951
+
952
+
// Apply byte constraints
953
+
this.applyBytesConstraints(byteDef, prop || scalar);
954
+
955
+
// Apply property-specific metadata
956
+
if (prop) {
957
+
this.applyPropertyMetadata(byteDef, prop);
958
+
}
959
+
960
+
return byteDef;
961
+
}
962
+
963
+
// Check if this scalar (or its base) is cidLink type
964
+
const isCidLink = this.isScalarCidLink(scalar);
965
+
966
+
if (isCidLink) {
967
+
const cidLinkDef: any = { type: "cid-link" };
968
+
969
+
// Apply property-specific metadata
970
+
if (prop) {
971
+
this.applyPropertyMetadata(cidLinkDef, prop);
972
+
}
973
+
974
+
return cidLinkDef;
942
975
}
943
976
944
977
// Determine base primitive type
···
961
994
return primitive;
962
995
}
963
996
997
+
private isScalarBytes(scalar: Scalar): boolean {
998
+
if (scalar.name === "bytes") return true;
999
+
if (scalar.baseScalar) return this.isScalarBytes(scalar.baseScalar);
1000
+
return false;
1001
+
}
1002
+
1003
+
private isScalarCidLink(scalar: Scalar): boolean {
1004
+
if (scalar.name === "cidLink") return true;
1005
+
if (scalar.baseScalar) return this.isScalarCidLink(scalar.baseScalar);
1006
+
return false;
1007
+
}
1008
+
964
1009
private getBasePrimitiveType(scalar: Scalar): any {
965
1010
if (scalar.name === "boolean") {
966
1011
return { type: "boolean" };
···
989
1034
990
1035
const minGraphemes = getMinGraphemes(this.program, target);
991
1036
if (minGraphemes !== undefined) primitive.minGraphemes = minGraphemes;
1037
+
}
1038
+
1039
+
private applyBytesConstraints(
1040
+
byteDef: any,
1041
+
target: Scalar | ModelProperty,
1042
+
) {
1043
+
const maxLength = getBytesMaxLength(this.program, target);
1044
+
if (maxLength !== undefined) byteDef.maxLength = maxLength;
992
1045
}
993
1046
994
1047
private applyNumericConstraints(primitive: any, prop?: ModelProperty) {
+2
packages/emitter/src/tsp-index.ts
+2
packages/emitter/src/tsp-index.ts
···
14
14
$encoding,
15
15
$errors,
16
16
$inline,
17
+
$bytesMaxLength,
17
18
} from "./decorators.js";
18
19
19
20
/** @internal */
···
33
34
encoding: $encoding,
34
35
errors: $errors,
35
36
inline: $inline,
37
+
bytesMaxLength: $bytesMaxLength,
36
38
},
37
39
"Tlex.Private": {
38
40
blob: $blob,
+7
packages/emitter/test/scenarios/atproto/input/com/atproto/identity/requestPlcOperationSignature.tsp
+7
packages/emitter/test/scenarios/atproto/input/com/atproto/identity/requestPlcOperationSignature.tsp
+22
packages/emitter/test/scenarios/atproto/input/com/atproto/identity/signPlcOperation.tsp
+22
packages/emitter/test/scenarios/atproto/input/com/atproto/identity/signPlcOperation.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.identity.signPlcOperation {
4
+
@doc("Signs a PLC operation to update some value(s) in the requesting DID's document.")
5
+
@procedure
6
+
op main(input: {
7
+
@doc("A token received through com.atproto.identity.requestPlcOperationSignature")
8
+
token?: string;
9
+
10
+
rotationKeys?: string[];
11
+
12
+
alsoKnownAs?: string[];
13
+
14
+
verificationMethods?: unknown;
15
+
16
+
services?: unknown;
17
+
}): {
18
+
@doc("A signed DID PLC operation.")
19
+
@required
20
+
operation: unknown;
21
+
};
22
+
}
+9
packages/emitter/test/scenarios/atproto/input/com/atproto/identity/submitPlcOperation.tsp
+9
packages/emitter/test/scenarios/atproto/input/com/atproto/identity/submitPlcOperation.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.identity.submitPlcOperation {
4
+
@doc("Validates a PLC operation to ensure that it doesn't violate a service's constraints or get the identity into a bad state, then submits it to the PLC registry")
5
+
@procedure
6
+
op main(input: {
7
+
@required operation: unknown;
8
+
}): void;
9
+
}
+10
packages/emitter/test/scenarios/atproto/input/com/atproto/repo/importRepo.tsp
+10
packages/emitter/test/scenarios/atproto/input/com/atproto/repo/importRepo.tsp
+22
packages/emitter/test/scenarios/atproto/input/com/atproto/repo/listMissingBlobs.tsp
+22
packages/emitter/test/scenarios/atproto/input/com/atproto/repo/listMissingBlobs.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.repo.listMissingBlobs {
4
+
@doc("Returns a list of missing blobs for the requesting account. Intended to be used in the account migration flow.")
5
+
@query
6
+
op main(
7
+
@minValue(1)
8
+
@maxValue(1000)
9
+
limit?: int32 = 500,
10
+
11
+
cursor?: string
12
+
): {
13
+
cursor?: string;
14
+
15
+
@required blobs: RecordBlob[];
16
+
};
17
+
18
+
model RecordBlob {
19
+
@required cid: cid;
20
+
@required recordUri: atUri;
21
+
}
22
+
}
+12
packages/emitter/test/scenarios/atproto/input/com/atproto/repo/uploadBlob.tsp
+12
packages/emitter/test/scenarios/atproto/input/com/atproto/repo/uploadBlob.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.repo.uploadBlob {
4
+
@doc("Upload a new blob, to be referenced from a repository record. The blob will be deleted if it is not referenced within a time window (eg, minutes). Blob restrictions (mimetype, size, etc) are enforced when the reference is created. Requires auth, implemented by PDS.")
5
+
@procedure
6
+
op main(
7
+
@encoding("*/*")
8
+
input: void
9
+
): {
10
+
@required blob: Blob<#[], 0>;
11
+
};
12
+
}
+23
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getBlob.tsp
+23
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getBlob.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.getBlob {
4
+
@doc("Get a blob associated with a given account. Returns the full blob as originally uploaded. Does not require auth; implemented by PDS.")
5
+
@query
6
+
@encoding("*/*")
7
+
@errors(BlobNotFound, RepoNotFound, RepoTakendown, RepoSuspended, RepoDeactivated)
8
+
op main(
9
+
@doc("The DID of the account.")
10
+
@required
11
+
did: did,
12
+
13
+
@doc("The CID of the blob to fetch")
14
+
@required
15
+
cid: cid
16
+
): void;
17
+
18
+
model BlobNotFound {}
19
+
model RepoNotFound {}
20
+
model RepoTakendown {}
21
+
model RepoSuspended {}
22
+
model RepoDeactivated {}
23
+
}
+21
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getBlocks.tsp
+21
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getBlocks.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.getBlocks {
4
+
@doc("Get data blocks from a given repo, by CID. For example, intermediate MST nodes, or records. Does not require auth; implemented by PDS.")
5
+
@query
6
+
@encoding("application/vnd.ipld.car")
7
+
@errors(BlockNotFound, RepoNotFound, RepoTakendown, RepoSuspended, RepoDeactivated)
8
+
op main(
9
+
@doc("The DID of the repo.")
10
+
@required
11
+
did: did,
12
+
13
+
@required cids: cid[]
14
+
): void;
15
+
16
+
model BlockNotFound {}
17
+
model RepoNotFound {}
18
+
model RepoTakendown {}
19
+
model RepoSuspended {}
20
+
model RepoDeactivated {}
21
+
}
+12
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getCheckout.tsp
+12
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getCheckout.tsp
+16
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getHead.tsp
+16
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getHead.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.getHead {
4
+
@doc("DEPRECATED - please use com.atproto.sync.getLatestCommit instead")
5
+
@query
6
+
@errors(HeadNotFound)
7
+
op main(
8
+
@doc("The DID of the repo.")
9
+
@required
10
+
did: did
11
+
): {
12
+
@required root: cid;
13
+
};
14
+
15
+
model HeadNotFound {}
16
+
}
+25
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getHostStatus.tsp
+25
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getHostStatus.tsp
···
1
+
import "@tlex/emitter";
2
+
import "./defs.tsp";
3
+
4
+
namespace com.atproto.sync.getHostStatus {
5
+
@doc("Returns information about a specified upstream host, as consumed by the server. Implemented by relays.")
6
+
@query
7
+
@errors(HostNotFound)
8
+
op main(
9
+
@doc("Hostname of the host (eg, PDS or relay) being queried.")
10
+
@required
11
+
hostname: string
12
+
): {
13
+
@required hostname: string;
14
+
15
+
@doc("Recent repo stream event sequence number. May be delayed from actual stream processing (eg, persisted cursor not in-memory cursor).")
16
+
seq?: integer;
17
+
18
+
@doc("Number of accounts on the server which are associated with the upstream host. Note that the upstream may actually have more accounts.")
19
+
accountCount?: integer;
20
+
21
+
status?: com.atproto.sync.defs.HostStatus;
22
+
};
23
+
24
+
model HostNotFound {}
25
+
}
+20
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getLatestCommit.tsp
+20
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getLatestCommit.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.getLatestCommit {
4
+
@doc("Get the current commit CID & revision of the specified repo. Does not require auth.")
5
+
@query
6
+
@errors(RepoNotFound, RepoTakendown, RepoSuspended, RepoDeactivated)
7
+
op main(
8
+
@doc("The DID of the repo.")
9
+
@required
10
+
did: did
11
+
): {
12
+
@required cid: cid;
13
+
@required rev: tid;
14
+
};
15
+
16
+
model RepoNotFound {}
17
+
model RepoTakendown {}
18
+
model RepoSuspended {}
19
+
model RepoDeactivated {}
20
+
}
+25
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getRecord.tsp
+25
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getRecord.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.getRecord {
4
+
@doc("Get data blocks needed to prove the existence or non-existence of record in the current version of repo. Does not require auth.")
5
+
@query
6
+
@encoding("application/vnd.ipld.car")
7
+
@errors(RecordNotFound, RepoNotFound, RepoTakendown, RepoSuspended, RepoDeactivated)
8
+
op main(
9
+
@doc("The DID of the repo.")
10
+
@required
11
+
did: did,
12
+
13
+
@required collection: nsid,
14
+
15
+
@doc("Record Key")
16
+
@required
17
+
rkey: recordKey
18
+
): void;
19
+
20
+
model RecordNotFound {}
21
+
model RepoNotFound {}
22
+
model RepoTakendown {}
23
+
model RepoSuspended {}
24
+
model RepoDeactivated {}
25
+
}
+21
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getRepo.tsp
+21
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getRepo.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.getRepo {
4
+
@doc("Download a repository export as CAR file. Optionally only a 'diff' since a previous revision. Does not require auth; implemented by PDS.")
5
+
@query
6
+
@encoding("application/vnd.ipld.car")
7
+
@errors(RepoNotFound, RepoTakendown, RepoSuspended, RepoDeactivated)
8
+
op main(
9
+
@doc("The DID of the repo.")
10
+
@required
11
+
did: did,
12
+
13
+
@doc("The revision ('rev') of the repo to create a diff from.")
14
+
since?: tid
15
+
): void;
16
+
17
+
model RepoNotFound {}
18
+
model RepoTakendown {}
19
+
model RepoSuspended {}
20
+
model RepoDeactivated {}
21
+
}
+23
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getRepoStatus.tsp
+23
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/getRepoStatus.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.getRepoStatus {
4
+
@doc("Get the hosting status for a repository, on this server. Expected to be implemented by PDS and Relay.")
5
+
@query
6
+
@errors(RepoNotFound)
7
+
op main(
8
+
@doc("The DID of the repo.")
9
+
@required
10
+
did: did
11
+
): {
12
+
@required did: did;
13
+
@required active: boolean;
14
+
15
+
@doc("If active=false, this optional field indicates a possible reason for why the account is not active. If active=false and no status is supplied, then the host makes no claim for why the repository is no longer being hosted.")
16
+
status?: "takendown" | "suspended" | "deleted" | "deactivated" | "desynchronized" | "throttled" | string;
17
+
18
+
@doc("Optional field, the current rev of the repo, if active=true")
19
+
rev?: tid;
20
+
};
21
+
22
+
model RepoNotFound {}
23
+
}
+29
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/listBlobs.tsp
+29
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/listBlobs.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.listBlobs {
4
+
@doc("List blob CIDs for an account, since some repo revision. Does not require auth; implemented by PDS.")
5
+
@query
6
+
@errors(RepoNotFound, RepoTakendown, RepoSuspended, RepoDeactivated)
7
+
op main(
8
+
@doc("The DID of the repo.")
9
+
@required
10
+
did: did,
11
+
12
+
@doc("Optional revision of the repo to list blobs since.")
13
+
since?: tid,
14
+
15
+
@minValue(1)
16
+
@maxValue(1000)
17
+
limit?: int32 = 500,
18
+
19
+
cursor?: string
20
+
): {
21
+
cursor?: string;
22
+
@required cids: cid[];
23
+
};
24
+
25
+
model RepoNotFound {}
26
+
model RepoTakendown {}
27
+
model RepoSuspended {}
28
+
model RepoDeactivated {}
29
+
}
+32
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/listHosts.tsp
+32
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/listHosts.tsp
···
1
+
import "@tlex/emitter";
2
+
import "./defs.tsp";
3
+
4
+
namespace com.atproto.sync.listHosts {
5
+
@doc("Enumerates upstream hosts (eg, PDS or relay instances) that this service consumes from. Implemented by relays.")
6
+
@query
7
+
op main(
8
+
@minValue(1)
9
+
@maxValue(1000)
10
+
limit?: int32 = 200,
11
+
12
+
cursor?: string
13
+
): {
14
+
cursor?: string;
15
+
16
+
@doc("Sort order is not formally specified. Recommended order is by time host was first seen by the server, with oldest first.")
17
+
@required
18
+
hosts: Host[];
19
+
};
20
+
21
+
model Host {
22
+
@doc("hostname of server; not a URL (no scheme)")
23
+
@required
24
+
hostname: string;
25
+
26
+
@doc("Recent repo stream event sequence number. May be delayed from actual stream processing (eg, persisted cursor not in-memory cursor).")
27
+
seq?: integer;
28
+
29
+
accountCount?: integer;
30
+
status?: com.atproto.sync.defs.HostStatus;
31
+
}
32
+
}
+30
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/listRepos.tsp
+30
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/listRepos.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.listRepos {
4
+
@doc("Enumerates all the DID, rev, and commit CID for all repos hosted by this service. Does not require auth; implemented by PDS and Relay.")
5
+
@query
6
+
op main(
7
+
@minValue(1)
8
+
@maxValue(1000)
9
+
limit?: int32 = 500,
10
+
11
+
cursor?: string
12
+
): {
13
+
cursor?: string;
14
+
@required repos: Repo[];
15
+
};
16
+
17
+
model Repo {
18
+
@required did: did;
19
+
20
+
@doc("Current repo commit CID")
21
+
@required
22
+
head: cid;
23
+
24
+
@required rev: tid;
25
+
active?: boolean;
26
+
27
+
@doc("If active=false, this optional field indicates a possible reason for why the account is not active. If active=false and no status is supplied, then the host makes no claim for why the repository is no longer being hosted.")
28
+
status?: "takendown" | "suspended" | "deleted" | "deactivated" | "desynchronized" | "throttled" | string;
29
+
}
30
+
}
+23
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/listReposByCollection.tsp
+23
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/listReposByCollection.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.listReposByCollection {
4
+
@doc("Enumerates all the DIDs which have records with the given collection NSID.")
5
+
@query
6
+
op main(
7
+
@required collection: nsid,
8
+
9
+
@doc("Maximum size of response set. Recommend setting a large maximum (1000+) when enumerating large DID lists.")
10
+
@minValue(1)
11
+
@maxValue(2000)
12
+
limit?: int32 = 500,
13
+
14
+
cursor?: string
15
+
): {
16
+
cursor?: string;
17
+
@required repos: Repo[];
18
+
};
19
+
20
+
model Repo {
21
+
@required did: did;
22
+
}
23
+
}
+11
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/notifyOfUpdate.tsp
+11
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/notifyOfUpdate.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.notifyOfUpdate {
4
+
@doc("Notify a crawling service of a recent update, and that crawling should resume. Intended use is after a gap between repo stream events caused the crawling service to disconnect. Does not require auth; implemented by Relay. DEPRECATED: just use com.atproto.sync.requestCrawl")
5
+
@procedure
6
+
op main(input: {
7
+
@doc("Hostname of the current service (usually a PDS) that is notifying of update.")
8
+
@required
9
+
hostname: string;
10
+
}): void;
11
+
}
+14
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/requestCrawl.tsp
+14
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/requestCrawl.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.requestCrawl {
4
+
@doc("Request a service to persistently crawl hosted repos. Expected use is new PDS instances declaring their existence to Relays. Does not require auth.")
5
+
@procedure
6
+
@errors(HostBanned)
7
+
op main(input: {
8
+
@doc("Hostname of the current service (eg, PDS) that is requesting to be crawled.")
9
+
@required
10
+
hostname: string;
11
+
}): void;
12
+
13
+
model HostBanned {}
14
+
}
+133
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/subscribeRepos.tsp
+133
packages/emitter/test/scenarios/atproto/input/com/atproto/sync/subscribeRepos.tsp
···
1
+
import "@tlex/emitter";
2
+
3
+
namespace com.atproto.sync.subscribeRepos {
4
+
@subscription
5
+
@errors(FutureCursor, ConsumerTooSlow)
6
+
@doc("Repository event stream, aka Firehose endpoint. Outputs repo commits with diff data, and identity update events, for all repositories on the current server. See the atproto specifications for details around stream sequencing, repo versioning, CAR diff format, and more. Public and does not require auth; implemented by PDS and Relay.")
7
+
op main(
8
+
@doc("The last known event seq number to backfill from.")
9
+
cursor?: integer
10
+
): (Commit | Sync | Identity | Account | Info | unknown);
11
+
12
+
model FutureCursor {}
13
+
14
+
@doc("If the consumer of the stream can not keep up with events, and a backlog gets too large, the server will drop the connection.")
15
+
model ConsumerTooSlow {}
16
+
17
+
@doc("Represents an update of repository state. Note that empty commits are allowed, which include no repo data changes, but an update to rev and signature.")
18
+
model Commit {
19
+
@doc("The stream sequence number of this message.")
20
+
@required
21
+
seq: integer;
22
+
23
+
@doc("DEPRECATED -- unused")
24
+
@required
25
+
rebase: boolean;
26
+
27
+
@doc("DEPRECATED -- replaced by #sync event and data limits. Indicates that this commit contained too many ops, or data size was too large. Consumers will need to make a separate request to get missing data.")
28
+
@required
29
+
tooBig: boolean;
30
+
31
+
@doc("The repo this event comes from. Note that all other message types name this field 'did'.")
32
+
@required
33
+
repo: did;
34
+
35
+
@doc("Repo commit object CID.")
36
+
@required
37
+
commit: cidLink;
38
+
39
+
@doc("The rev of the emitted commit. Note that this information is also in the commit object included in blocks, unless this is a tooBig event.")
40
+
@required
41
+
rev: tid;
42
+
43
+
@doc("The rev of the last emitted commit from this repo (if any).")
44
+
@required
45
+
since: tid | null;
46
+
47
+
@doc("CAR file containing relevant blocks, as a diff since the previous repo state. The commit must be included as a block, and the commit block CID must be the first entry in the CAR header 'roots' list.")
48
+
@bytesMaxLength(2000000)
49
+
@required
50
+
blocks: bytes;
51
+
52
+
@maxItems(200)
53
+
@required
54
+
@doc("List of repo mutation operations in this commit (eg, records created, updated, or deleted).")
55
+
ops: RepoOp[];
56
+
57
+
@doc("DEPRECATED -- will soon always be empty. List of new blobs (by CID) referenced by records in this commit.")
58
+
@required blobs: cidLink[];
59
+
60
+
@doc("The root CID of the MST tree for the previous commit from this repo (indicated by the 'since' revision field in this message). Corresponds to the 'data' field in the repo commit object. NOTE: this field is effectively required for the 'inductive' version of firehose.")
61
+
prevData?: cidLink;
62
+
63
+
@doc("Timestamp of when this message was originally broadcast.")
64
+
@required
65
+
time: datetime;
66
+
}
67
+
68
+
@doc("Updates the repo to a new state, without necessarily including that state on the firehose. Used to recover from broken commit streams, data loss incidents, or in situations where upstream host does not know recent state of the repository.")
69
+
model Sync {
70
+
@doc("The stream sequence number of this message.")
71
+
@required
72
+
seq: integer;
73
+
74
+
@doc("The account this repo event corresponds to. Must match that in the commit object.")
75
+
@required
76
+
did: did;
77
+
78
+
@doc("CAR file containing the commit, as a block. The CAR header must include the commit block CID as the first 'root'.")
79
+
@bytesMaxLength(10000)
80
+
@required
81
+
blocks: bytes;
82
+
83
+
@doc("The rev of the commit. This value must match that in the commit object.")
84
+
@required
85
+
rev: string;
86
+
87
+
@doc("Timestamp of when this message was originally broadcast.")
88
+
@required
89
+
time: datetime;
90
+
}
91
+
92
+
@doc("Represents a change to an account's identity. Could be an updated handle, signing key, or pds hosting endpoint. Serves as a prod to all downstream services to refresh their identity cache.")
93
+
model Identity {
94
+
@required seq: integer;
95
+
@required did: did;
96
+
@required time: datetime;
97
+
98
+
@doc("The current handle for the account, or 'handle.invalid' if validation fails. This field is optional, might have been validated or passed-through from an upstream source. Semantics and behaviors for PDS vs Relay may evolve in the future; see atproto specs for more details.")
99
+
handle?: handle;
100
+
}
101
+
102
+
@doc("Represents a change to an account's status on a host (eg, PDS or Relay). The semantics of this event are that the status is at the host which emitted the event, not necessarily that at the currently active PDS. Eg, a Relay takedown would emit a takedown with active=false, even if the PDS is still active.")
103
+
model Account {
104
+
@required seq: integer;
105
+
@required did: did;
106
+
@required time: datetime;
107
+
108
+
@doc("Indicates that the account has a repository which can be fetched from the host that emitted this event.")
109
+
@required
110
+
active: boolean;
111
+
112
+
@doc("If active=false, this optional field indicates a reason for why the account is not active.")
113
+
status?: "takendown" | "suspended" | "deleted" | "deactivated" | "desynchronized" | "throttled" | string;
114
+
}
115
+
116
+
model Info {
117
+
@required name: "OutdatedCursor" | string;
118
+
message?: string;
119
+
}
120
+
121
+
@doc("A repo operation, ie a mutation of a single record.")
122
+
model RepoOp {
123
+
@required action: "create" | "update" | "delete" | string;
124
+
@required path: string;
125
+
126
+
@doc("For creates and updates, the new record CID. For deletions, null.")
127
+
@required
128
+
cid: cidLink | null;
129
+
130
+
@doc("For updates and deletes, the previous record CID (required for inductive firehose). For creations, field should not be defined.")
131
+
prev?: cidLink;
132
+
}
133
+
}
+4
-4
packages/emitter/test/scenarios/atproto/output/com/atproto/sync/subscribeRepos.json
+4
-4
packages/emitter/test/scenarios/atproto/output/com/atproto/sync/subscribeRepos.json
···
81
81
},
82
82
"ops": {
83
83
"type": "array",
84
+
"description": "List of repo mutation operations in this commit (eg, records created, updated, or deleted).",
84
85
"items": {
85
86
"type": "ref",
86
-
"ref": "#repoOp",
87
-
"description": "List of repo mutation operations in this commit (eg, records created, updated, or deleted)."
87
+
"ref": "#repoOp"
88
88
},
89
89
"maxLength": 200
90
90
},
91
91
"blobs": {
92
92
"type": "array",
93
+
"description": "DEPRECATED -- will soon always be empty. List of new blobs (by CID) referenced by records in this commit.",
93
94
"items": {
94
-
"type": "cid-link",
95
-
"description": "DEPRECATED -- will soon always be empty. List of new blobs (by CID) referenced by records in this commit."
95
+
"type": "cid-link"
96
96
}
97
97
},
98
98
"prevData": {