database.go (7197B)
1 package pub 2 3 import ( 4 "context" 5 "net/url" 6 7 "github.com/superseriousbusiness/activity/streams/vocab" 8 ) 9 10 type Database interface { 11 // Lock takes a lock for the object at the specified id. If an error 12 // is returned, the lock must not have been taken. 13 // 14 // The lock must be able to succeed for an id that does not exist in 15 // the database. This means acquiring the lock does not guarantee the 16 // entry exists in the database. 17 // 18 // Locks are encouraged to be lightweight and in the Go layer, as some 19 // processes require tight loops acquiring and releasing locks. 20 // 21 // Used to ensure race conditions in multiple requests do not occur. 22 Lock(c context.Context, id *url.URL) (unlock func(), err error) 23 // InboxContains returns true if the OrderedCollection at 'inbox' 24 // contains the specified 'id'. 25 // 26 // The library makes this call only after acquiring a lock first. 27 InboxContains(c context.Context, inbox, id *url.URL) (contains bool, err error) 28 // GetInbox returns the first ordered collection page of the outbox at 29 // the specified IRI, for prepending new items. 30 // 31 // The library makes this call only after acquiring a lock first. 32 GetInbox(c context.Context, inboxIRI *url.URL) (inbox vocab.ActivityStreamsOrderedCollectionPage, err error) 33 // SetInbox saves the inbox value given from GetInbox, with new items 34 // prepended. Note that the new items must not be added as independent 35 // database entries. Separate calls to Create will do that. 36 // 37 // The library makes this call only after acquiring a lock first. 38 SetInbox(c context.Context, inbox vocab.ActivityStreamsOrderedCollectionPage) error 39 // Owns returns true if the database has an entry for the IRI and it 40 // exists in the database. 41 // 42 // The library makes this call only after acquiring a lock first. 43 Owns(c context.Context, id *url.URL) (owns bool, err error) 44 // ActorForOutbox fetches the actor's IRI for the given outbox IRI. 45 // 46 // The library makes this call only after acquiring a lock first. 47 ActorForOutbox(c context.Context, outboxIRI *url.URL) (actorIRI *url.URL, err error) 48 // ActorForInbox fetches the actor's IRI for the given outbox IRI. 49 // 50 // The library makes this call only after acquiring a lock first. 51 ActorForInbox(c context.Context, inboxIRI *url.URL) (actorIRI *url.URL, err error) 52 // OutboxForInbox fetches the corresponding actor's outbox IRI for the 53 // actor's inbox IRI. 54 // 55 // The library makes this call only after acquiring a lock first. 56 OutboxForInbox(c context.Context, inboxIRI *url.URL) (outboxIRI *url.URL, err error) 57 // InboxesForIRI fetches inboxes corresponding to the given iri. 58 // This allows your server to skip remote dereferencing of iris 59 // in order to speed up message delivery, if desired. 60 // 61 // It is acceptable to just return nil or an empty slice for the inboxIRIs, 62 // if you don't know the inbox iri, or you don't wish to use this feature. 63 // In this case, the library will attempt to resolve inboxes of the iri 64 // by remote dereferencing instead. 65 // 66 // If the input iri is the iri of an Actor, then the inbox for the actor 67 // should be returned as a single-entry slice. 68 // 69 // If the input iri is a Collection (such as a Collection of followers), 70 // then each follower inbox IRI should be returned in the inboxIRIs slice. 71 // 72 // The library makes this call only after acquiring a lock first. 73 InboxesForIRI(c context.Context, iri *url.URL) (inboxIRIs []*url.URL, err error) 74 // Exists returns true if the database has an entry for the specified 75 // id. It may not be owned by this application instance. 76 // 77 // The library makes this call only after acquiring a lock first. 78 Exists(c context.Context, id *url.URL) (exists bool, err error) 79 // Get returns the database entry for the specified id. 80 // 81 // The library makes this call only after acquiring a lock first. 82 Get(c context.Context, id *url.URL) (value vocab.Type, err error) 83 // Create adds a new entry to the database which must be able to be 84 // keyed by its id. 85 // 86 // Note that Activity values received from federated peers may also be 87 // created in the database this way if the Federating Protocol is 88 // enabled. The client may freely decide to store only the id instead of 89 // the entire value. 90 // 91 // The library makes this call only after acquiring a lock first. 92 // 93 // Under certain conditions and network activities, Create may be called 94 // multiple times for the same ActivityStreams object. 95 Create(c context.Context, asType vocab.Type) error 96 // Update sets an existing entry to the database based on the value's 97 // id. 98 // 99 // Note that Activity values received from federated peers may also be 100 // updated in the database this way if the Federating Protocol is 101 // enabled. The client may freely decide to store only the id instead of 102 // the entire value. 103 // 104 // The library makes this call only after acquiring a lock first. 105 Update(c context.Context, asType vocab.Type) error 106 // Delete removes the entry with the given id. 107 // 108 // Delete is only called for federated objects. Deletes from the Social 109 // Protocol instead call Update to create a Tombstone. 110 // 111 // The library makes this call only after acquiring a lock first. 112 Delete(c context.Context, id *url.URL) error 113 // GetOutbox returns the first ordered collection page of the outbox 114 // at the specified IRI, for prepending new items. 115 // 116 // The library makes this call only after acquiring a lock first. 117 GetOutbox(c context.Context, outboxIRI *url.URL) (outbox vocab.ActivityStreamsOrderedCollectionPage, err error) 118 // SetOutbox saves the outbox value given from GetOutbox, with new items 119 // prepended. Note that the new items must not be added as independent 120 // database entries. Separate calls to Create will do that. 121 // 122 // The library makes this call only after acquiring a lock first. 123 SetOutbox(c context.Context, outbox vocab.ActivityStreamsOrderedCollectionPage) error 124 // NewID creates a new IRI id for the provided activity or object. The 125 // implementation does not need to set the 'id' property and simply 126 // needs to determine the value. 127 // 128 // The go-fed library will handle setting the 'id' property on the 129 // activity or object provided with the value returned. 130 NewID(c context.Context, t vocab.Type) (id *url.URL, err error) 131 // Followers obtains the Followers Collection for an actor with the 132 // given id. 133 // 134 // If modified, the library will then call Update. 135 // 136 // The library makes this call only after acquiring a lock first. 137 Followers(c context.Context, actorIRI *url.URL) (followers vocab.ActivityStreamsCollection, err error) 138 // Following obtains the Following Collection for an actor with the 139 // given id. 140 // 141 // If modified, the library will then call Update. 142 // 143 // The library makes this call only after acquiring a lock first. 144 Following(c context.Context, actorIRI *url.URL) (following vocab.ActivityStreamsCollection, err error) 145 // Liked obtains the Liked Collection for an actor with the 146 // given id. 147 // 148 // If modified, the library will then call Update. 149 // 150 // The library makes this call only after acquiring a lock first. 151 Liked(c context.Context, actorIRI *url.URL) (liked vocab.ActivityStreamsCollection, err error) 152 }