commit e343e796480eb536c6b1aeaa4b7d586f67787a9c · dwn.poxiao-labs.work/atpasser

+103 -4

src/atpasser/uri/__init__.py

···

       1
        
       import urllib.parse as up

     

       2
       -
       from . import handle, did

     

       3
        
       import jsonpath_ng

     

       4
       -
       from .exceptions import InvalidURIError, ValidationError, URIError

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       5
        
       

     

       6
        
       

     

       7
        
       class URI:

     
···

       159
        
       

     

       160
        
               self.authorityAsText = authorityValue

     

       161
        
               try:

     

       162
       -
                   authority = handle.Handle(authorityValue)

     

       163
        
               except Exception as e:

     

       164
        
                   try:

     

       165
       -
                       authority = did.DID(authorityValue)

     

       166
        
                   except Exception as e2:

     

       167
        
                       # Don't throw exception, just set authority to None

     

       168
        
                       authority = None

     
···

       207
        
               else:

     

       208
        
       

     

       209
        
                   return False

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0

···

       1
        
       import urllib.parse as up

     

       2
       +
       from .identifier import Handle, DID

     

       3
        
       import jsonpath_ng

     

       4
       +
       from .exceptions import (

     

       5
       +
           InvalidURIError,

     

       6
       +
           ValidationError,

     

       7
       +
           URIError,

     

       8
       +
           InvalidRestrictedURIError,

     

       9
       +
       )

     

       10
        
       

     

       11
        
       

     

       12
        
       class URI:

     
···

       164
        
       

     

       165
        
               self.authorityAsText = authorityValue

     

       166
        
               try:

     

       167
       +
                   authority = Handle(authorityValue)

     

       168
        
               except Exception as e:

     

       169
        
                   try:

     

       170
       +
                       authority = DID(authorityValue)

     

       171
        
                   except Exception as e2:

     

       172
        
                       # Don't throw exception, just set authority to None

     

       173
        
                       authority = None

     
···

       212
        
               else:

     

       213
        
       

     

       214
        
                   return False

     

       215
       +
       

     

       216
       +
       

     

       217
       +
       from .identifier import Handle

     

       218
       +
       from . import nsid

     

       219
       +
       from . import rkey as rKey

     

       220
       +
       from . import URI

     

       221
       +
       

     

       222
       +
       

     

       223
       +
       class RestrictedURI(URI):

     

       224
       +
           """A class representing a restricted AT Protocol URI for record access.

     

       225
       +
       

     

       226
       +
           RestrictedURIs provide a specialized form of AT Protocol URIs that specifically

     

       227
       +
           address records within repositories. They follow the format 'at://authority/collection/rkey'

     

       228
       +
           where collection identifies the record type (via NSID) and rkey identifies the specific

     

       229
       +
           record instance. This format is commonly used for referencing specific social records

     

       230
       +
           like posts, profiles, and other user-generated content.

     

       231
       +
       

     

       232
       +
           Attributes:

     

       233
       +
               collection (atpasser.uri.NSID): The record collection identified by NSID.

     

       234
       +
               rkey (atpasser.uri.RKey): The record key identifying a specific record instance.

     

       235
       +
           """

     

       236
       +
       

     

       237
       +
           def __init__(self, uri: str) -> None:

     

       238
       +
               """Initializes a restricted URI with validation.

     

       239
       +
       

     

       240
       +
               Parses and validates an AT Protocol URI specifically for record access.

     

       241
       +
               Restricted URIs must have a valid authority (DID or handle), may include

     

       242
       +
               a collection (NSID), and optionally a record key (rkey). Query parameters

     

       243
       +
               and fragments are not allowed in restricted URIs.

     

       244
       +
       

     

       245
       +
               Args:

     

       246
       +
                   uri (str): The AT Protocol URI string to parse as a restricted URI.

     

       247
       +
       

     

       248
       +
               Raises:

     

       249
       +
                   InvalidRestrictedURIError: If the URI has query parameters or fragments, invalid authority,

     

       250
       +
                                           or too many path segments for a restricted URI format.

     

       251
       +
                   InvalidURIError: If the underlying URI validation fails.

     

       252
       +
               """

     

       253
       +
       

     

       254
       +
               try:

     

       255
       +
                   super().__init__(uri)

     

       256
       +
               except InvalidURIError:

     

       257
       +
                   raise

     

       258
       +
               except Exception as e:

     

       259
       +
                   raise InvalidURIError(

     

       260
       +
                       uri, "base URI validation failed", f"Failed to parse base URI: {str(e)}"

     

       261
       +
                   )

     

       262
       +
       

     

       263
       +
               if self.query is not None:

     

       264
       +
                   raise InvalidRestrictedURIError(

     

       265
       +
                       uri,

     

       266
       +
                       "query parameters not supported",

     

       267
       +
                       "Restricted URI cannot contain query parameters",

     

       268
       +
                   )

     

       269
       +
       

     

       270
       +
               if self.fragment is not None:

     

       271
       +
                   raise InvalidRestrictedURIError(

     

       272
       +
                       uri,

     

       273
       +
                       "fragments not supported",

     

       274
       +
                       "Restricted URI cannot contain fragments",

     

       275
       +
                   )

     

       276
       +
       

     

       277
       +
               if self.authority is None:

     

       278
       +
                   raise InvalidRestrictedURIError(

     

       279
       +
                       uri,

     

       280
       +
                       "invalid authority",

     

       281
       +
                       "Restricted URI must contain a valid DID or Handle",

     

       282
       +
                   )

     

       283
       +
       

     

       284
       +
               try:

     

       285
       +
                   if len(self.path) == 0:

     

       286
       +
                       self.collection, self.rkey = None, None

     

       287
       +
       

     

       288
       +
                   elif len(self.path) == 1:

     

       289
       +
                       self.collection = nsid.NSID(self.path[0])

     

       290
       +
                       self.rkey = None

     

       291
       +
       

     

       292
       +
                   elif len(self.path) == 2:

     

       293
       +
                       self.collection = nsid.NSID(self.path[0])

     

       294
       +
                       self.rkey = rKey.RKey(self.path[1])

     

       295
       +
                   else:

     

       296
       +
                       raise InvalidRestrictedURIError(

     

       297
       +
                           uri,

     

       298
       +
                           "too many path segments",

     

       299
       +
                           f"Restricted URI can have at most 2 path segments, currently has {len(self.path)}",

     

       300
       +
                       )

     

       301
       +
               except Exception as e:

     

       302
       +
                   if isinstance(e, (InvalidRestrictedURIError, InvalidURIError)):

     

       303
       +
                       raise

     

       304
       +
                   raise InvalidRestrictedURIError(

     

       305
       +
                       uri,

     

       306
       +
                       "parsing error",

     

       307
       +
                       f"Error occurred while parsing Restricted URI: {str(e)}",

     

       308
       +
                   )

-112

src/atpasser/uri/did.py

···

       1
       -
       import re

     

       2
       -
       from pyld import jsonld

     

       3
       -
       from .exceptions import InvalidDIDError, ResolutionError

     

       4
       -
       

     

       5
       -
       

     

       6
       -
       class DID:

     

       7
       -
           """A class representing a DID (Decentralized Identifier) in the AT Protocol.

     

       8
       -
       

     

       9
       -
           Decentralized Identifiers (DIDs) are a key component of the AT Protocol's identity system.

     

       10
       -
           They provide cryptographically verifiable, persistent identifiers for users and services

     

       11
       -
           in the decentralized network. DIDs follow the format 'did:method:specific-identifier'

     

       12
       -
           where method defines the resolution mechanism (e.g., 'plc' for PLC directory, 'web' for web-based).

     

       13
       -
       

     

       14
       -
           Attributes:

     

       15
       -
               uri (str): The complete DID URI string.

     

       16
       -
           """

     

       17
       -
       

     

       18
       -
           def __init__(self, uri: str) -> None:

     

       19
       -
               """Initializes a DID object with validation.

     

       20
       -
       

     

       21
       -
               Parses and validates a DID URI string according to the W3C DID specification

     

       22
       -
               and AT Protocol requirements. The DID must follow the format 'did:method:identifier'

     

       23
       -
               and contain only valid characters.

     

       24
       -
       

     

       25
       -
               Args:

     

       26
       -
                   uri (str): The DID URI string to validate.

     

       27
       -
       

     

       28
       -
               Raises:

     

       29
       -
                   InvalidDIDError: If the URI doesn't match the DID format or exceeds maximum length.

     

       30
       -
               """

     

       31
       -
               pattern = re.compile("^did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-]$")

     

       32
       -
               patternMatch = pattern.match(uri)

     

       33
       -
       

     

       34
       -
               if not patternMatch:

     

       35
       -
                   raise InvalidDIDError(

     

       36
       -
                       uri, "invalid format", "DID must follow 'did:method:identifier' format"

     

       37
       -
                   )

     

       38
       -
       

     

       39
       -
               if len(uri) > 2048:

     

       40
       -
                   raise InvalidDIDError(

     

       41
       -
                       uri,

     

       42
       -
                       "exceeds maximum length",

     

       43
       -
                       f"DID length {len(uri)} exceeds maximum allowed length of 2048 characters",

     

       44
       -
                   )

     

       45
       -
       

     

       46
       -
               self.uri = patternMatch[0]

     

       47
       -
       

     

       48
       -
           def __str__(self) -> str:

     

       49
       -
               """Convert the DID object to its string representation.

     

       50
       -
       

     

       51
       -
               Returns:

     

       52
       -
                   str: The canonical DID URI string.

     

       53
       -
               """

     

       54
       -
               return self.uri

     

       55
       -
       

     

       56
       -
           def __eq__(self, value: object, /) -> bool:

     

       57
       -
               """Check if two DID objects represent the same identifier.

     

       58
       -
       

     

       59
       -
               Args:

     

       60
       -
                   value (object): The object to compare with.

     

       61
       -
       

     

       62
       -
               Returns:

     

       63
       -
                   bool: True if the objects represent the same DID, False otherwise.

     

       64
       -
               """

     

       65
       -
               if isinstance(value, DID):

     

       66
       -
                   return str(self) == str(value)

     

       67
       -
               else:

     

       68
       -
                   return False

     

       69
       -
       

     

       70
       -
           def fetch(self):

     

       71
       -
               """Fetch the DID document metadata from the appropriate resolver.

     

       72
       -
       

     

       73
       -
               Resolves the DID to its associated DID document by querying the appropriate

     

       74
       -
               resolver based on the DID method. Currently supports 'did:plc:' (resolved via

     

       75
       -
               PLC directory) and 'did:web:' (resolved via well-known HTTP endpoint).

     

       76
       -
       

     

       77
       -
               Returns:

     

       78
       -
                   list: The expanded JSON-LD document representing the DID document,

     

       79
       -
                         compatible with the PyLD library for further processing.

     

       80
       -
       

     

       81
       -
               Raises:

     

       82
       -
                   ResolutionError: If the DID document cannot be fetched or parsed.

     

       83
       -
                   InvalidDIDError: If the DID method is not supported.

     

       84
       -
       

     

       85
       -
               Note:

     

       86
       -
                   - For 'did:plc:' DIDs, queries https://plc.directory/{did}

     

       87
       -
                   - For 'did:web:' DIDs, queries https://{domain}/.well-known/did.json

     

       88
       -
               """

     

       89
       -
               try:

     

       90
       -
                   if self.uri.startswith("did:plc:"):

     

       91
       -
                       return jsonld.expand(f"https://plc.directory/{self.uri}")

     

       92
       -
                   elif self.uri.startswith("did:web:"):

     

       93
       -
                       domain = self.uri.replace("did:web:", "")

     

       94
       -
                       if not domain:

     

       95
       -
                           raise InvalidDIDError(

     

       96
       -
                               self.uri, "invalid format", "did:web DID must contain a domain"

     

       97
       -
                           )

     

       98
       -
                       return jsonld.expand(f"https://{domain}/.well-known/did.json")

     

       99
       -
                   else:

     

       100
       -
                       raise InvalidDIDError(

     

       101
       -
                           self.uri,

     

       102
       -
                           "unsupported DID method",

     

       103
       -
                           f"Unsupported DID method: {self.uri.split(':')[1]}",

     

       104
       -
                       )

     

       105
       -
               except Exception as e:

     

       106
       -
                   if isinstance(e, (InvalidDIDError, ResolutionError)):

     

       107
       -
                       raise

     

       108
       -
                   raise ResolutionError(

     

       109
       -
                       self.uri,

     

       110
       -
                       "fetch DID document",

     

       111
       -
                       f"Failed to fetch or parse DID document: {str(e)}",

     

       112
       -
                   )

+116 -2

src/atpasser/uri/handle.py src/atpasser/uri/identifier.py

···

       0
        
       
     

       0
        
       
     

       1
        
       import dns.resolver, requests

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       2
        
       

     

       3
       -
       from .did import DID

     

       4
       -
       from .exceptions import InvalidHandleError, ResolutionError, InvalidDIDError

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       5
        
       

     

       6
        
       

     

       7
        
       class Handle:

···

       1
       +
       import re

     

       2
       +
       from pyld import jsonld

     

       3
        
       import dns.resolver, requests

     

       4
       +
       from .exceptions import (

     

       5
       +
           InvalidDIDError,

     

       6
       +
           InvalidHandleError,

     

       7
       +
           ResolutionError,

     

       8
       +
           InvalidDIDError,

     

       9
       +
       )

     

       10
        
       

     

       11
       +
       

     

       12
       +
       class DID:

     

       13
       +
           """A class representing a DID (Decentralized Identifier) in the AT Protocol.

     

       14
       +
       

     

       15
       +
           Decentralized Identifiers (DIDs) are a key component of the AT Protocol's identity system.

     

       16
       +
           They provide cryptographically verifiable, persistent identifiers for users and services

     

       17
       +
           in the decentralized network. DIDs follow the format 'did:method:specific-identifier'

     

       18
       +
           where method defines the resolution mechanism (e.g., 'plc' for PLC directory, 'web' for web-based).

     

       19
       +
       

     

       20
       +
           Attributes:

     

       21
       +
               uri (str): The complete DID URI string.

     

       22
       +
           """

     

       23
       +
       

     

       24
       +
           def __init__(self, uri: str) -> None:

     

       25
       +
               """Initializes a DID object with validation.

     

       26
       +
       

     

       27
       +
               Parses and validates a DID URI string according to the W3C DID specification

     

       28
       +
               and AT Protocol requirements. The DID must follow the format 'did:method:identifier'

     

       29
       +
               and contain only valid characters.

     

       30
       +
       

     

       31
       +
               Args:

     

       32
       +
                   uri (str): The DID URI string to validate.

     

       33
       +
       

     

       34
       +
               Raises:

     

       35
       +
                   InvalidDIDError: If the URI doesn't match the DID format or exceeds maximum length.

     

       36
       +
               """

     

       37
       +
               pattern = re.compile("^did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-]$")

     

       38
       +
               patternMatch = pattern.match(uri)

     

       39
       +
       

     

       40
       +
               if not patternMatch:

     

       41
       +
                   raise InvalidDIDError(

     

       42
       +
                       uri, "invalid format", "DID must follow 'did:method:identifier' format"

     

       43
       +
                   )

     

       44
       +
       

     

       45
       +
               if len(uri) > 2048:

     

       46
       +
                   raise InvalidDIDError(

     

       47
       +
                       uri,

     

       48
       +
                       "exceeds maximum length",

     

       49
       +
                       f"DID length {len(uri)} exceeds maximum allowed length of 2048 characters",

     

       50
       +
                   )

     

       51
       +
       

     

       52
       +
               self.uri = patternMatch[0]

     

       53
       +
       

     

       54
       +
           def __str__(self) -> str:

     

       55
       +
               """Convert the DID object to its string representation.

     

       56
       +
       

     

       57
       +
               Returns:

     

       58
       +
                   str: The canonical DID URI string.

     

       59
       +
               """

     

       60
       +
               return self.uri

     

       61
       +
       

     

       62
       +
           def __eq__(self, value: object, /) -> bool:

     

       63
       +
               """Check if two DID objects represent the same identifier.

     

       64
       +
       

     

       65
       +
               Args:

     

       66
       +
                   value (object): The object to compare with.

     

       67
       +
       

     

       68
       +
               Returns:

     

       69
       +
                   bool: True if the objects represent the same DID, False otherwise.

     

       70
       +
               """

     

       71
       +
               if isinstance(value, DID):

     

       72
       +
                   return str(self) == str(value)

     

       73
       +
               else:

     

       74
       +
                   return False

     

       75
       +
       

     

       76
       +
           def fetch(self):

     

       77
       +
               """Fetch the DID document metadata from the appropriate resolver.

     

       78
       +
       

     

       79
       +
               Resolves the DID to its associated DID document by querying the appropriate

     

       80
       +
               resolver based on the DID method. Currently supports 'did:plc:' (resolved via

     

       81
       +
               PLC directory) and 'did:web:' (resolved via well-known HTTP endpoint).

     

       82
       +
       

     

       83
       +
               Returns:

     

       84
       +
                   list: The expanded JSON-LD document representing the DID document,

     

       85
       +
                         compatible with the PyLD library for further processing.

     

       86
       +
       

     

       87
       +
               Raises:

     

       88
       +
                   ResolutionError: If the DID document cannot be fetched or parsed.

     

       89
       +
                   InvalidDIDError: If the DID method is not supported.

     

       90
       +
       

     

       91
       +
               Note:

     

       92
       +
                   - For 'did:plc:' DIDs, queries https://plc.directory/{did}

     

       93
       +
                   - For 'did:web:' DIDs, queries https://{domain}/.well-known/did.json

     

       94
       +
               """

     

       95
       +
               try:

     

       96
       +
                   if self.uri.startswith("did:plc:"):

     

       97
       +
                       return jsonld.expand(f"https://plc.directory/{self.uri}")

     

       98
       +
                   elif self.uri.startswith("did:web:"):

     

       99
       +
                       domain = self.uri.replace("did:web:", "")

     

       100
       +
                       if not domain:

     

       101
       +
                           raise InvalidDIDError(

     

       102
       +
                               self.uri, "invalid format", "did:web DID must contain a domain"

     

       103
       +
                           )

     

       104
       +
                       return jsonld.expand(f"https://{domain}/.well-known/did.json")

     

       105
       +
                   else:

     

       106
       +
                       raise InvalidDIDError(

     

       107
       +
                           self.uri,

     

       108
       +
                           "unsupported DID method",

     

       109
       +
                           f"Unsupported DID method: {self.uri.split(':')[1]}",

     

       110
       +
                       )

     

       111
       +
               except Exception as e:

     

       112
       +
                   if isinstance(e, (InvalidDIDError, ResolutionError)):

     

       113
       +
                       raise

     

       114
       +
                   raise ResolutionError(

     

       115
       +
                       self.uri,

     

       116
       +
                       "fetch DID document",

     

       117
       +
                       f"Failed to fetch or parse DID document: {str(e)}",

     

       118
       +
                   )

     

       119
        
       

     

       120
        
       

     

       121
        
       class Handle:

-92

src/atpasser/uri/restricted.py

···

       1
       -
       from . import handle, nsid

     

       2
       -
       from . import rkey as rKey

     

       3
       -
       from . import URI

     

       4
       -
       from .exceptions import InvalidRestrictedURIError, InvalidURIError

     

       5
       -
       

     

       6
       -
       

     

       7
       -
       class RestrictedURI(URI):

     

       8
       -
           """A class representing a restricted AT Protocol URI for record access.

     

       9
       -
       

     

       10
       -
           RestrictedURIs provide a specialized form of AT Protocol URIs that specifically

     

       11
       -
           address records within repositories. They follow the format 'at://authority/collection/rkey'

     

       12
       -
           where collection identifies the record type (via NSID) and rkey identifies the specific

     

       13
       -
           record instance. This format is commonly used for referencing specific social records

     

       14
       -
           like posts, profiles, and other user-generated content.

     

       15
       -
       

     

       16
       -
           Attributes:

     

       17
       -
               collection (atpasser.uri.NSID): The record collection identified by NSID.

     

       18
       -
               rkey (atpasser.uri.RKey): The record key identifying a specific record instance.

     

       19
       -
           """

     

       20
       -
       

     

       21
       -
           def __init__(self, uri: str) -> None:

     

       22
       -
               """Initializes a restricted URI with validation.

     

       23
       -
       

     

       24
       -
               Parses and validates an AT Protocol URI specifically for record access.

     

       25
       -
               Restricted URIs must have a valid authority (DID or handle), may include

     

       26
       -
               a collection (NSID), and optionally a record key (rkey). Query parameters

     

       27
       -
               and fragments are not allowed in restricted URIs.

     

       28
       -
       

     

       29
       -
               Args:

     

       30
       -
                   uri (str): The AT Protocol URI string to parse as a restricted URI.

     

       31
       -
       

     

       32
       -
               Raises:

     

       33
       -
                   InvalidRestrictedURIError: If the URI has query parameters or fragments, invalid authority,

     

       34
       -
                                           or too many path segments for a restricted URI format.

     

       35
       -
                   InvalidURIError: If the underlying URI validation fails.

     

       36
       -
               """

     

       37
       -
       

     

       38
       -
               try:

     

       39
       -
                   super().__init__(uri)

     

       40
       -
               except InvalidURIError:

     

       41
       -
                   raise

     

       42
       -
               except Exception as e:

     

       43
       -
                   raise InvalidURIError(

     

       44
       -
                       uri, "base URI validation failed", f"Failed to parse base URI: {str(e)}"

     

       45
       -
                   )

     

       46
       -
       

     

       47
       -
               if self.query is not None:

     

       48
       -
                   raise InvalidRestrictedURIError(

     

       49
       -
                       uri,

     

       50
       -
                       "query parameters not supported",

     

       51
       -
                       "Restricted URI cannot contain query parameters",

     

       52
       -
                   )

     

       53
       -
       

     

       54
       -
               if self.fragment is not None:

     

       55
       -
                   raise InvalidRestrictedURIError(

     

       56
       -
                       uri,

     

       57
       -
                       "fragments not supported",

     

       58
       -
                       "Restricted URI cannot contain fragments",

     

       59
       -
                   )

     

       60
       -
       

     

       61
       -
               if self.authority is None:

     

       62
       -
                   raise InvalidRestrictedURIError(

     

       63
       -
                       uri,

     

       64
       -
                       "invalid authority",

     

       65
       -
                       "Restricted URI must contain a valid DID or Handle",

     

       66
       -
                   )

     

       67
       -
       

     

       68
       -
               try:

     

       69
       -
                   if len(self.path) == 0:

     

       70
       -
                       self.collection, self.rkey = None, None

     

       71
       -
       

     

       72
       -
                   elif len(self.path) == 1:

     

       73
       -
                       self.collection = nsid.NSID(self.path[0])

     

       74
       -
                       self.rkey = None

     

       75
       -
       

     

       76
       -
                   elif len(self.path) == 2:

     

       77
       -
                       self.collection = nsid.NSID(self.path[0])

     

       78
       -
                       self.rkey = rKey.RKey(self.path[1])

     

       79
       -
                   else:

     

       80
       -
                       raise InvalidRestrictedURIError(

     

       81
       -
                           uri,

     

       82
       -
                           "too many path segments",

     

       83
       -
                           f"Restricted URI can have at most 2 path segments, currently has {len(self.path)}",

     

       84
       -
                       )

     

       85
       -
               except Exception as e:

     

       86
       -
                   if isinstance(e, (InvalidRestrictedURIError, InvalidURIError)):

     

       87
       -
                       raise

     

       88
       -
                   raise InvalidRestrictedURIError(

     

       89
       -
                       uri,

     

       90
       -
                       "parsing error",

     

       91
       -
                       f"Error occurred while parsing Restricted URI: {str(e)}",

     

       92
       -
                   )

+157

src/atpasser/uri/rkey.py

···

       90
        
                   return str(self) == str(value)

     

       91
        
               else:

     

       92
        
                   return False

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0

···

       90
        
                   return str(self) == str(value)

     

       91
        
               else:

     

       92
        
                   return False

     

       93
       +
       

     

       94
       +
       

     

       95
       +
       import datetime, random

     

       96
       +
       

     

       97
       +
       

     

       98
       +
       class TID(RKey):

     

       99
       +
           """A class representing a TID (Time-based Identifier) in the AT Protocol.

     

       100
       +
       

     

       101
       +
           TIDs are time-based identifiers used for ordering and uniquely identifying

     

       102
       +
           records in the AT Protocol. They combine a microsecond-precision timestamp

     

       103
       +
           with a clock identifier to ensure uniqueness even when multiple records

     

       104
       +
           are created in the same microsecond. TIDs are sortable and provide both

     

       105
       +
           temporal ordering and uniqueness guarantees.

     

       106
       +
       

     

       107
       +
           Attributes:

     

       108
       +
               timestamp (datetime.datetime): The timestamp component of the TID.

     

       109
       +
               clockIdentifier (int): Clock identifier (0-1023) for disambiguation.

     

       110
       +
               recordKey (str): The record key string identifying a specific record.

     

       111
       +
           """

     

       112
       +
       

     

       113
       +
           def __init__(

     

       114
       +
               self, time: datetime.datetime | None = None, clockIdentifier: int | None = None

     

       115
       +
           ) -> None:

     

       116
       +
               """Initializes a TID object with timestamp and clock identifier.

     

       117
       +
       

     

       118
       +
               Creates a new TID with the specified timestamp and clock identifier.

     

       119
       +
               If no timestamp is provided, uses the current time. If no clock identifier

     

       120
       +
               is provided, generates a random value between 0-1023.

     

       121
       +
       

     

       122
       +
               Args:

     

       123
       +
                   time (datetime.datetime, optional): The timestamp for the TID.

     

       124
       +
                       Defaults to current time if not provided.

     

       125
       +
                   clockIdentifier (int, optional): Clock identifier (0-1023) for

     

       126
       +
                       disambiguation. Defaults to random value if not provided.

     

       127
       +
               """

     

       128
       +
               if time == None:

     

       129
       +
                   self.timestamp = datetime.datetime.now()

     

       130
       +
               else:

     

       131
       +
                   self.timestamp = time

     

       132
       +
               if clockIdentifier == None:

     

       133
       +
                   self.clockIdentifier = random.randrange(0, 1024)

     

       134
       +
               else:

     

       135
       +
                   self.clockIdentifier = clockIdentifier

     

       136
       +
       

     

       137
       +
               # Generate TID string representation, then call parent class constructor

     

       138
       +
               tid_string = self._generate_tid_string()

     

       139
       +
               super().__init__(tid_string)

     

       140
       +
       

     

       141
       +
           def _generate_tid_string(self) -> str:

     

       142
       +
               """Generate TID string representation.

     

       143
       +
       

     

       144
       +
               Returns:

     

       145
       +
                   str: The base32 string representation of the TID.

     

       146
       +
               """

     

       147
       +
               integer = (

     

       148
       +
                   int(self.timestamp.timestamp() * 1000000) * 1024 + self.clockIdentifier

     

       149
       +
               )

     

       150
       +
               binary = f"{integer:065b}"

     

       151
       +
               return "".join(

     

       152
       +
                   [

     

       153
       +
                       "234567abcdefghijklmnopqrstuvwxyz"[int(binary[i : i + 5], base=2)]

     

       154
       +
                       for i in range(0, len(binary), 5)

     

       155
       +
                   ]

     

       156
       +
               )

     

       157
       +
       

     

       158
       +
           def __int__(self):

     

       159
       +
               """Convert the TID to its integer representation.

     

       160
       +
       

     

       161
       +
               Combines the timestamp (in microseconds) and clock identifier into

     

       162
       +
               a single 64-bit integer where the high bits represent the timestamp

     

       163
       +
               and the low 10 bits represent the clock identifier.

     

       164
       +
       

     

       165
       +
               Returns:

     

       166
       +
                   int: The integer representation of the TID.

     

       167
       +
               """

     

       168
       +
               timestamp = int(self.timestamp.timestamp() * 1000000)

     

       169
       +
               return timestamp * 1024 + self.clockIdentifier

     

       170
       +
       

     

       171
       +
           def __str__(self):

     

       172
       +
               """Convert the TID to a base32-sortable string representation.

     

       173
       +
       

     

       174
       +
               Encodes the TID as a base32 string using a custom character set that

     

       175
       +
               maintains lexicographical sort order corresponding to temporal order.

     

       176
       +
               This format is commonly used in the AT Protocol for compact,

     

       177
       +
               sortable identifiers.

     

       178
       +
       

     

       179
       +
               Returns:

     

       180
       +
                   str: The base32 string representation of the TID.

     

       181
       +
               """

     

       182
       +
               # Use parent class __str__ method, which returns recordKey

     

       183
       +
               return super().__str__()

     

       184
       +
       

     

       185
       +
           def __eq__(self, value: object, /) -> bool:

     

       186
       +
               """Check if two TID objects represent the same identifier.

     

       187
       +
       

     

       188
       +
               Args:

     

       189
       +
                   value (object): The object to compare with.

     

       190
       +
       

     

       191
       +
               Returns:

     

       192
       +
                   bool: True if the objects represent the same TID, False otherwise.

     

       193
       +
               """

     

       194
       +
               if isinstance(value, TID):

     

       195
       +
                   return int(self) == int(value)

     

       196
       +
               elif isinstance(value, RKey):

     

       197
       +
                   # If comparing with RKey, use string comparison

     

       198
       +
                   return str(self) == str(value)

     

       199
       +
               else:

     

       200
       +
                   return False

     

       201
       +
       

     

       202
       +
       

     

       203
       +
       def importTIDfromInteger(value: int | None = None):

     

       204
       +
           """Create a TID object from an integer representation.

     

       205
       +
       

     

       206
       +
           Converts a 64-bit integer back into a TID object by extracting the

     

       207
       +
           timestamp and clock identifier components. If no value is provided,

     

       208
       +
           creates a TID for the current time.

     

       209
       +
       

     

       210
       +
           Args:

     

       211
       +
               value (int, optional): The integer value to convert to a TID.

     

       212
       +
                   Defaults to creating a TID for the current time if not provided.

     

       213
       +
       

     

       214
       +
           Returns:

     

       215
       +
               TID: The TID object created from the integer value.

     

       216
       +
           """

     

       217
       +
           if value == None:

     

       218
       +
               value = int(TID())

     

       219
       +
           clockIdentifier = value % 1024

     

       220
       +
           timestamp = (value >> 10) / 1000000

     

       221
       +
           return TID(datetime.datetime.fromtimestamp(timestamp), clockIdentifier)

     

       222
       +
       

     

       223
       +
       

     

       224
       +
       def importTIDfromBase32(value: str | None = None):

     

       225
       +
           """Create a TID object from a base32 string representation.

     

       226
       +
       

     

       227
       +
           Converts a base32-encoded TID string back into a TID object by decoding

     

       228
       +
           the string to its integer representation and then extracting the timestamp

     

       229
       +
           and clock identifier components. If no value is provided, creates a TID

     

       230
       +
           for the current time.

     

       231
       +
       

     

       232
       +
           Args:

     

       233
       +
               value (str, optional): The base32 string to convert to a TID.

     

       234
       +
                   Defaults to creating a TID for the current time if not provided.

     

       235
       +
       

     

       236
       +
           Returns:

     

       237
       +
               TID: The TID object created from the base32 string.

     

       238
       +
           """

     

       239
       +
           if value == None:

     

       240
       +
               value = str(TID())

     

       241
       +
           b32s = "234567abcdefghijklmnopqrstuvwxyz"

     

       242
       +
           return importTIDfromInteger(

     

       243
       +
               sum(

     

       244
       +
                   [

     

       245
       +
                       b32s.find(value[i]) * (32 ** (len(value) - i - 1))

     

       246
       +
                       for i in range(len(value))

     

       247
       +
                   ]

     

       248
       +
               )

     

       249
       +
           )

-136

src/atpasser/uri/tid.py

···

       1
       -
       import datetime, random

     

       2
       -
       

     

       3
       -
       

     

       4
       -
       class TID:

     

       5
       -
           """A class representing a TID (Time-based Identifier) in the AT Protocol.

     

       6
       -
       

     

       7
       -
           TIDs are time-based identifiers used for ordering and uniquely identifying

     

       8
       -
           records in the AT Protocol. They combine a microsecond-precision timestamp

     

       9
       -
           with a clock identifier to ensure uniqueness even when multiple records

     

       10
       -
           are created in the same microsecond. TIDs are sortable and provide both

     

       11
       -
           temporal ordering and uniqueness guarantees.

     

       12
       -
       

     

       13
       -
           Attributes:

     

       14
       -
               timestamp (datetime.datetime): The timestamp component of the TID.

     

       15
       -
               clockIdentifier (int): Clock identifier (0-1023) for disambiguation.

     

       16
       -
           """

     

       17
       -
       

     

       18
       -
           def __init__(

     

       19
       -
               self, time: datetime.datetime | None = None, clockIdentifier: int | None = None

     

       20
       -
           ) -> None:

     

       21
       -
               """Initializes a TID object with timestamp and clock identifier.

     

       22
       -
       

     

       23
       -
               Creates a new TID with the specified timestamp and clock identifier.

     

       24
       -
               If no timestamp is provided, uses the current time. If no clock identifier

     

       25
       -
               is provided, generates a random value between 0-1023.

     

       26
       -
       

     

       27
       -
               Args:

     

       28
       -
                   time (datetime.datetime, optional): The timestamp for the TID.

     

       29
       -
                       Defaults to current time if not provided.

     

       30
       -
                   clockIdentifier (int, optional): Clock identifier (0-1023) for

     

       31
       -
                       disambiguation. Defaults to random value if not provided.

     

       32
       -
               """

     

       33
       -
               if time == None:

     

       34
       -
                   self.timestamp = datetime.datetime.now()

     

       35
       -
               else:

     

       36
       -
                   self.timestamp = time

     

       37
       -
               if clockIdentifier == None:

     

       38
       -
                   self.clockIdentifier = random.randrange(0, 1024)

     

       39
       -
               else:

     

       40
       -
                   self.clockIdentifier = clockIdentifier

     

       41
       -
       

     

       42
       -
           def __int__(self):

     

       43
       -
               """Convert the TID to its integer representation.

     

       44
       -
       

     

       45
       -
               Combines the timestamp (in microseconds) and clock identifier into

     

       46
       -
               a single 64-bit integer where the high bits represent the timestamp

     

       47
       -
               and the low 10 bits represent the clock identifier.

     

       48
       -
       

     

       49
       -
               Returns:

     

       50
       -
                   int: The integer representation of the TID.

     

       51
       -
               """

     

       52
       -
               timestamp = int(self.timestamp.timestamp() * 1000000)

     

       53
       -
               return timestamp * 1024 + self.clockIdentifier

     

       54
       -
       

     

       55
       -
           def __str__(self):

     

       56
       -
               """Convert the TID to a base32-sortable string representation.

     

       57
       -
       

     

       58
       -
               Encodes the TID as a base32 string using a custom character set that

     

       59
       -
               maintains lexicographical sort order corresponding to temporal order.

     

       60
       -
               This format is commonly used in the AT Protocol for compact,

     

       61
       -
               sortable identifiers.

     

       62
       -
       

     

       63
       -
               Returns:

     

       64
       -
                   str: The base32 string representation of the TID.

     

       65
       -
               """

     

       66
       -
               integer = int(self)

     

       67
       -
               binary = f"{integer:065b}"

     

       68
       -
               return "".join(

     

       69
       -
                   [

     

       70
       -
                       "234567abcdefghijklmnopqrstuvwxyz"[int(binary[i : i + 5], base=2)]

     

       71
       -
                       for i in range(0, len(binary), 5)

     

       72
       -
                   ]

     

       73
       -
               )

     

       74
       -
       

     

       75
       -
           def __eq__(self, value: object, /) -> bool:

     

       76
       -
               """Check if two TID objects represent the same identifier.

     

       77
       -
       

     

       78
       -
               Args:

     

       79
       -
                   value (object): The object to compare with.

     

       80
       -
       

     

       81
       -
               Returns:

     

       82
       -
                   bool: True if the objects represent the same TID, False otherwise.

     

       83
       -
               """

     

       84
       -
               if isinstance(value, TID):

     

       85
       -
                   return int(self) == int(value)

     

       86
       -
               else:

     

       87
       -
                   return False

     

       88
       -
       

     

       89
       -
       

     

       90
       -
       def importTIDfromInteger(value: int | None = None):

     

       91
       -
           """Create a TID object from an integer representation.

     

       92
       -
       

     

       93
       -
           Converts a 64-bit integer back into a TID object by extracting the

     

       94
       -
           timestamp and clock identifier components. If no value is provided,

     

       95
       -
           creates a TID for the current time.

     

       96
       -
       

     

       97
       -
           Args:

     

       98
       -
               value (int, optional): The integer value to convert to a TID.

     

       99
       -
                   Defaults to creating a TID for the current time if not provided.

     

       100
       -
       

     

       101
       -
           Returns:

     

       102
       -
               TID: The TID object created from the integer value.

     

       103
       -
           """

     

       104
       -
           if value == None:

     

       105
       -
               value = int(TID())

     

       106
       -
           clockIdentifier = value % 1024

     

       107
       -
           timestamp = (value >> 10) / 1000000

     

       108
       -
           return TID(datetime.datetime.fromtimestamp(timestamp), clockIdentifier)

     

       109
       -
       

     

       110
       -
       

     

       111
       -
       def importTIDfromBase32(value: str | None = None):

     

       112
       -
           """Create a TID object from a base32 string representation.

     

       113
       -
       

     

       114
       -
           Converts a base32-encoded TID string back into a TID object by decoding

     

       115
       -
           the string to its integer representation and then extracting the timestamp

     

       116
       -
           and clock identifier components. If no value is provided, creates a TID

     

       117
       -
           for the current time.

     

       118
       -
       

     

       119
       -
           Args:

     

       120
       -
               value (str, optional): The base32 string to convert to a TID.

     

       121
       -
                   Defaults to creating a TID for the current time if not provided.

     

       122
       -
       

     

       123
       -
           Returns:

     

       124
       -
               TID: The TID object created from the base32 string.

     

       125
       -
           """

     

       126
       -
           if value == None:

     

       127
       -
               value = str(TID())

     

       128
       -
           b32s = "234567abcdefghijklmnopqrstuvwxyz"

     

       129
       -
           return importTIDfromInteger(

     

       130
       -
               sum(

     

       131
       -
                   [

     

       132
       -
                       b32s.find(value[i]) * (32 ** (len(value) - i - 1))

     

       133
       -
                       for i in range(len(value))

     

       134
       -
                   ]

     

       135
       -
               )

     

       136
       -
           )