mooncakes.io

README

marianoguerra/atproto/syntax does not have a README file

#
SyntaxError

pub(all) suberror SyntaxError {
  SyntaxError(kind~ : SyntaxKind, input~ : String, reason~ : String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

impl Show for SyntaxError

#
SyntaxError::describe_error

source

fn SyntaxError::describe_error(self : SyntaxError) -> String

The input is truncated: a DID may be 2048 characters and an AT-URI 8192, and a validation failure that floods a log is its own bug.

#
SyntaxError::input

source

fn SyntaxError::input(self : SyntaxError) -> String

#
SyntaxError::kind

source

fn SyntaxError::kind(self : SyntaxError) -> SyntaxKind

#
SyntaxError::reason

source

fn SyntaxError::reason(self : SyntaxError) -> String

The upstream message, on its own. Callers rendering their own text want this rather than describe_error, which adds the offending input.

#
AtIdentifier

source

pub(all) enum AtIdentifier {
  Did(Did)
  Handle(Handle)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

impl Show for AtIdentifier

#
AtIdentifier::as_did

source

fn AtIdentifier::as_did(self : AtIdentifier) -> Did?

The DID, if this is one. None for a handle -- resolving a handle to a DID needs the network and is a client call, not a syntax operation.

#
AtIdentifier::as_handle

source

fn AtIdentifier::as_handle(self : AtIdentifier) -> Handle?

#
AtIdentifier::is_valid

source

fn AtIdentifier::is_valid(input : String) -> Bool

#
AtIdentifier::parse

source

fn AtIdentifier::parse(input : String) -> AtIdentifier raise SyntaxError

The did: prefix decides which validator runs, so a malformed DID is reported as a bad DID rather than as a bad handle -- did:thing is not a handle that happens to contain a colon.

#
AtIdentifier::to_string

source

fn AtIdentifier::to_string(self : AtIdentifier) -> String

#
AtUri

source

pub struct AtUri {
  authority : AtIdentifier
  path : AtUriPath
  fragment : String?
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A syntactically valid AT-URI.

impl Show for AtUri

#
AtUri::authority

source

fn AtUri::authority(self : AtUri) -> AtIdentifier

#
AtUri::collection

source

fn AtUri::collection(self : AtUri) -> Nsid?

#
AtUri::fragment

source

fn AtUri::fragment(self : AtUri) -> String?

#
AtUri::is_valid

source

fn AtUri::is_valid(uri : String) -> Bool

#
AtUri::make

source

fn AtUri::make(authority : AtIdentifier, path : AtUriPath, fragment? : String) -> AtUri

Builds an AT-URI from parts that are already valid, so it cannot fail. This is the constructor to reach for when you have a DID and a record key in hand rather than a string to interpret.

#
AtUri::parse

source

fn AtUri::parse(uri : String) -> AtUri raise SyntaxError

Note what this does NOT accept, all of which the older AtUri class did: a missing at:// prefix, a trailing slash, a query string, and a record key that is not a valid record key. Every one of those is in the protocol's interop corpus as invalid.

#
AtUri::path

source

fn AtUri::path(self : AtUri) -> AtUriPath

#
AtUri::rkey

source

fn AtUri::rkey(self : AtUri) -> RecordKey?

#
AtUri::to_string

source

fn AtUri::to_string(self : AtUri) -> String

#
AtUriPath

source

pub(all) enum AtUriPath {
  Repo
  Collection(Nsid)
  Record(collection~ : Nsid, rkey~ : RecordKey)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

What an AT-URI points at. A record key without a collection is not a state this type can hold.

#
Cid

source

pub struct Cid {
  text : String
  version : Int
  codec : CidCodec
  hash_code : Int
  hash_length : Int
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A parsed CID, holding the string it came from.

As everywhere else in this package the original bytes are what re-serializes, which for a CID matters twice over: it is a content hash, so a re-encoding that differs is a reference to nothing.

impl Show for Cid

#
Cid::codec

source

fn Cid::codec(self : Cid) -> CidCodec

#
Cid::hash_code

source

fn Cid::hash_code(self : Cid) -> Int

#
Cid::is_valid

source

fn Cid::is_valid(text : String) -> Bool

#
Cid::parse

source

fn Cid::parse(text : String) -> Cid raise SyntaxError

#
Cid::to_string

source

fn Cid::to_string(self : Cid) -> String

#
Cid::unchecked

source

fn Cid::unchecked(text : String) -> Cid

Trusts the caller. The header fields are reported as a CIDv1 SHA-256 DAG-CBOR CID, which is what atproto writes -- so do not read them off a value you built this way.

#
Cid::version

source

fn Cid::version(self : Cid) -> Int

#
CidCodec

source

pub(all) enum CidCodec {
  Raw
  DagCbor
  DagPb
  Other(Int)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Multicodec content types, the ones atproto uses.

#
CidCodec::code

source

fn CidCodec::code(self : CidCodec) -> Int

#
Datetime

source

pub struct Datetime(String) derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A syntactically and semantically valid RFC 3339 datetime, holding the exact bytes it was parsed from.

impl Show for Datetime

#
Datetime::from_epoch_millis

source

fn Datetime::from_epoch_millis(millis : Int64) -> Datetime

Builds a UTC datetime with millisecond precision -- 1985-04-12T23:20:50.123Z, the spelling the spec calls "preferred" and the one to write when creating a record.

The clock is an argument, as everywhere else in this package.

#
Datetime::is_valid

source

fn Datetime::is_valid(value : String) -> Bool

#
Datetime::parse

source

fn Datetime::parse(value : String) -> Datetime raise SyntaxError

#
Datetime::parts

source

fn Datetime::parts(self : Datetime) -> DatetimeParts

#
Datetime::to_epoch_seconds

source

fn Datetime::to_epoch_seconds(self : Datetime) -> Int64

Seconds since the Unix epoch, with the offset applied. Sub-second precision is dropped; parts().fraction still has it.

#
Datetime::to_string

source

fn Datetime::to_string(self : Datetime) -> String

#
Datetime::unchecked

source

fn Datetime::unchecked(value : String) -> Datetime

#
DatetimeParts

source

pub struct DatetimeParts {
  year : Int
  month : Int
  day : Int
  hour : Int
  minute : Int
  second : Int
  fraction : String
  offset_minutes : Int
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

The parsed pieces. Kept alongside the string rather than replacing it, so callers can do arithmetic without the value losing its original spelling.

#
Did

source

pub struct Did(String) derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A syntactically valid DID.

Opaque: the only ways in are parse, which checks, and unchecked, which says in its name that it does not.

impl Show for Did

#
Did::is_valid

source

fn Did::is_valid(did : String) -> Bool

#
Did::method_name

source

fn Did::method_name(self : Did) -> String

The method: plc in did:plc:7iza6de2dwap2sbkpav7c6c6.

Spelled method_name because method is a reserved word.

Total, because a Did cannot exist without one.

#
Did::parse

source

fn Did::parse(did : String) -> Did raise SyntaxError

The order of these checks is upstream's, and it is observable: a caller sees the message for the FIRST rule an input breaks, so reordering them changes the reported reason for inputs that break several. DID:method:val must report a missing prefix, not an uppercase method.

#
Did::to_string

source

fn Did::to_string(self : Did) -> String

#
Did::unchecked

source

fn Did::unchecked(did : String) -> Did

Trusts the caller. For values that have already been validated -- read back out of a database this library wrote, or decoded from a response that was checked at the boundary -- and for tests.

#
Handle

source

pub struct Handle(String) derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A syntactically valid handle. Always lower-case: parse normalizes, because handles are domain names and DNS is case-insensitive, so treating Alice.BSky.social and alice.bsky.social as different values would be a bug waiting to be written.

impl Show for Handle

#
Handle::is_invalid_sentinel

source

fn Handle::is_invalid_sentinel(self : Handle) -> Bool

True for the handle.invalid sentinel a PDS returns when it could not verify a handle against its DID document. Such a value is well-formed, so nothing else in this package will flag it.

#
Handle::is_valid

source

fn Handle::is_valid(handle : String) -> Bool

#
Handle::is_valid_tld

source

fn Handle::is_valid_tld(self : Handle) -> Bool

Whether the handle's TLD is one atproto permits. Separate from parse because it is policy: the list has changed and will change again, and a handle that stops being allowed does not retroactively stop being well-formed.

#
Handle::parse

source

fn Handle::parse(handle : String) -> Handle raise SyntaxError

Lower-casing is safe to do before validating rather than after because the character-set gate rejects everything outside ASCII, so no locale-dependent case mapping can apply.

#
Handle::to_string

source

fn Handle::to_string(self : Handle) -> String

#
Handle::unchecked

source

fn Handle::unchecked(handle : String) -> Handle

Trusts the caller, and does NOT normalize -- unchecked means unchecked.

#
Language

source

pub struct Language(String) derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A well-formed BCP 47 language tag, holding the bytes it was parsed from. Case is meaningful to readers by convention but not to equality in the protocol; nothing here normalizes, because a record must round-trip.

impl Show for Language

#
Language::is_valid

source

fn Language::is_valid(tag : String) -> Bool

#
Language::is_well_formed

source

fn Language::is_well_formed(tag : String) -> Bool

RFC 5646 §2.1 well-formedness, and nothing more. This is the level the Lexicon language format applies, so it is the one a decoder should use on a value arriving from a server -- being stricter than the protocol would mean rejecting records other clients happily wrote.

#
Language::parse

source

fn Language::parse(tag : String) -> Language raise SyntaxError

Well-formed and valid: a lowercase 2-3 letter primary subtag, no repeated variant, no repeated extension singleton.

#
Language::parse_lenient

source

fn Language::parse_lenient(tag : String) -> Language raise SyntaxError

Well-formedness only. See parse for the stricter reading.

#
Language::primary

source

fn Language::primary(self : Language) -> String?

The primary language subtag -- en in en-GB-boont. None for a private-use-only tag, which names no language.

#
Language::to_string

source

fn Language::to_string(self : Language) -> String

#
Language::unchecked

source

fn Language::unchecked(tag : String) -> Language

#
Nsid

source

pub struct Nsid(String) derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A syntactically valid NSID.

impl Show for Nsid

#
Nsid::authority

source

fn Nsid::authority(self : Nsid) -> String

The publishing authority, as a domain name -- so app.bsky.feed.post has authority bsky.app. The segments are reversed back into DNS order, which is the form you would look up or check a certificate against.

#
Nsid::is_valid

source

fn Nsid::is_valid(nsid : String) -> Bool

#
Nsid::name

source

fn Nsid::name(self : Nsid) -> String

The name part -- post in app.bsky.feed.post.

#
Nsid::parse

source

fn Nsid::parse(nsid : String) -> Nsid raise SyntaxError

#
Nsid::to_string

source

fn Nsid::to_string(self : Nsid) -> String

#
Nsid::unchecked

source

fn Nsid::unchecked(nsid : String) -> Nsid

#
RecordKey

source

pub struct RecordKey(String) derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A syntactically valid record key.

impl Show for RecordKey

#
RecordKey::is_valid

source

fn RecordKey::is_valid(rkey : String) -> Bool

#
RecordKey::parse

source

fn RecordKey::parse(rkey : String) -> RecordKey raise SyntaxError

The order matters for the message, and for one substantive reason: . and .. both satisfy the character set, so checking the set first would report them as a syntax failure rather than as the reserved path components they are. They are excluded because a record key is also a path segment in the repository's Merkle tree.

#
RecordKey::to_string

source

fn RecordKey::to_string(self : RecordKey) -> String

#
RecordKey::unchecked

source

fn RecordKey::unchecked(rkey : String) -> RecordKey

#
SyntaxKind

source

pub(all) enum SyntaxKind {
  Did
  Handle
  AtIdentifier
  Nsid
  RecordKey
  Tid
  AtUri
  Datetime
  Language
  Uri
  Cid
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Which syntax a value failed to satisfy.

#
SyntaxKind::label

source

fn SyntaxKind::label(self : SyntaxKind) -> String

The name used in error messages, matching the reference implementation's spelling -- "ATURI" and "NSID" are shouted upstream, so they are here.

#
Ticker

source

pub struct Ticker {
  clock_id : Int
  last : Int64
}

Mints TIDs that increase even when the clock does not.

Two calls in the same microsecond -- or across a clock that has gone backwards -- must not produce the same key or a decreasing one, because a repository's records are ordered by it. So the ticker keeps the last value it issued and steps past it, which costs a microsecond of drift and buys monotonicity.

#
Ticker::new

source

fn Ticker::new(clock_id : Int) -> Ticker

clock_id should be random per process; this package will not draw it, because a random number needs a source and a source needs a platform.

#
Ticker::next

source

fn Ticker::next(self : Ticker, now_micros : Int64) -> Tid

#
Tid

source

pub struct Tid(String) derive(Compare, Eq, @moonbitlang/core/debug.Debug
Debug)

A syntactically valid TID.

Compare is derived from the string, which is correct precisely because of the sortable alphabet -- see the note above before changing it.

impl Show for Tid

#
Tid::clock_id

source

fn Tid::clock_id(self : Tid) -> Int

The writer's random per-process identifier. Carries no meaning beyond breaking ties between two TIDs minted in the same microsecond.

#
Tid::from_time

source

fn Tid::from_time(micros : Int64, clock_id : Int) -> Tid

Builds a TID from an explicit time. The clock is an argument rather than a call to now() so that this package needs no platform clock and stays buildable on every backend -- the same reason @ratectl in the sibling slack library takes now : Int64.

micros is truncated to 53 bits and clock_id to 10, which is what makes this total: there is no input for which it produces an invalid TID.

#
Tid::is_valid

source

fn Tid::is_valid(tid : String) -> Bool

#
Tid::parse

source

fn Tid::parse(tid : String) -> Tid raise SyntaxError

#
Tid::timestamp

source

fn Tid::timestamp(self : Tid) -> Int64

Microseconds since the Unix epoch.

#
Tid::to_string

source

fn Tid::to_string(self : Tid) -> String

#
Tid::unchecked

source

fn Tid::unchecked(tid : String) -> Tid

#
Uri

source

pub struct Uri(String) derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A string shaped like a URI.

impl Show for Uri

#
Uri::is_valid

source

fn Uri::is_valid(uri : String) -> Bool

#
Uri::parse

source

fn Uri::parse(uri : String) -> Uri raise SyntaxError

#
Uri::scheme

source

fn Uri::scheme(self : Uri) -> String

The scheme, lower-cased -- https in https://example.com. This is the part worth branching on, and the reason to have a type here at all.

#
Uri::to_string

source

fn Uri::to_string(self : Uri) -> String

#
Uri::unchecked

source

fn Uri::unchecked(uri : String) -> Uri

#
INVALID_HANDLE

source

let INVALID_HANDLE : String

What a PDS returns in place of a handle when it has one on file but could not bidirectionally verify it against the DID document. It is deliberately itself a syntactically valid handle, so it flows through code that does not check -- which is precisely why code that displays a handle should.

#
disallowed_tlds

source

let disallowed_tlds : Array[String]

TLDs a handle may not use. Policy, not syntax: these strings parse fine and are refused for what they mean, so parse does not consult this list and is_valid_tld is a separate question.

.test is deliberately absent -- it is allowed, for development.

Source Files

Site source Report issue Packages Build queue Skills Statistics

#SyntaxError

#SyntaxError::describe_error

#SyntaxError::input

#SyntaxError::kind

#SyntaxError::reason

#AtIdentifier

#AtIdentifier::as_did

#AtIdentifier::as_handle

#AtIdentifier::is_valid

#AtIdentifier::parse

#AtIdentifier::to_string

#AtUri

#AtUri::authority

#AtUri::collection

#AtUri::fragment

#AtUri::is_valid

#AtUri::make

#AtUri::parse

#AtUri::path

#AtUri::rkey

#AtUri::to_string

#AtUriPath

#Cid

#Cid::codec

#Cid::hash_code

#Cid::is_valid

#Cid::parse

#Cid::to_string

#Cid::unchecked

#Cid::version

#CidCodec

#CidCodec::code

#Datetime

#Datetime::from_epoch_millis

#Datetime::is_valid

#Datetime::parse

#Datetime::parts

#Datetime::to_epoch_seconds

#Datetime::to_string

#Datetime::unchecked

#DatetimeParts

#Did

#Did::is_valid

#Did::method_name

#Did::parse

#Did::to_string

#Did::unchecked

#Handle

#Handle::is_invalid_sentinel

#Handle::is_valid

#Handle::is_valid_tld

#Handle::parse

#Handle::to_string

#Handle::unchecked

#Language

#Language::is_valid

#Language::is_well_formed

#Language::parse

#Language::parse_lenient

#Language::primary

#Language::to_string

#Language::unchecked

#Nsid

#Nsid::authority

#Nsid::is_valid

#Nsid::name

#Nsid::parse

#Nsid::to_string

#Nsid::unchecked

#RecordKey

#RecordKey::is_valid

#RecordKey::parse

#RecordKey::to_string

#RecordKey::unchecked

#SyntaxKind

#SyntaxKind::label

#Ticker

#Ticker::new

#Ticker::next

#Tid

#
SyntaxError

#
SyntaxError::describe_error

#
SyntaxError::input

#
SyntaxError::kind

#
SyntaxError::reason

#
AtIdentifier

#
AtIdentifier::as_did

#
AtIdentifier::as_handle

#
AtIdentifier::is_valid

#
AtIdentifier::parse

#
AtIdentifier::to_string

#
AtUri

#
AtUri::authority

#
AtUri::collection

#
AtUri::fragment

#
AtUri::is_valid

#
AtUri::make

#
AtUri::parse

#
AtUri::path

#
AtUri::rkey

#
AtUri::to_string

#
AtUriPath

#
Cid

#
Cid::codec

#
Cid::hash_code

#
Cid::is_valid

#
Cid::parse

#
Cid::to_string

#
Cid::unchecked

#
Cid::version

#
CidCodec

#
CidCodec::code

#
Datetime

#
Datetime::from_epoch_millis

#
Datetime::is_valid

#
Datetime::parse

#
Datetime::parts

#
Datetime::to_epoch_seconds

#
Datetime::to_string

#
Datetime::unchecked

#
DatetimeParts

#
Did

#
Did::is_valid

#
Did::method_name

#
Did::parse

#
Did::to_string

#
Did::unchecked

#
Handle

#
Handle::is_invalid_sentinel

#
Handle::is_valid

#
Handle::is_valid_tld

#
Handle::parse

#
Handle::to_string

#
Handle::unchecked

#
Language

#
Language::is_valid

#
Language::is_well_formed

#
Language::parse

#
Language::parse_lenient

#
Language::primary

#
Language::to_string

#
Language::unchecked

#
Nsid

#
Nsid::authority

#
Nsid::is_valid

#
Nsid::name

#
Nsid::parse

#
Nsid::to_string

#
Nsid::unchecked

#
RecordKey

#
RecordKey::is_valid

#
RecordKey::parse

#
RecordKey::to_string

#
RecordKey::unchecked

#
SyntaxKind

#
SyntaxKind::label

#
Ticker

#
Ticker::new

#
Ticker::next

#
Tid