@commitspark/graphql-api 2.0.0-beta.4 → 2.0.0-beta.5

package/src/graphql/resolvers/query-mutation-resolvers/mutation-update-resolver.ts

@@ -1,9 +1,14 @@
-import { findByTypeId } from '../../../persistence/persistence.ts'
+import {
+  assertExpectedVersion,
+  findByTypeId,
+} from '../../../persistence/persistence.ts'
 import { validateEntryReferences } from '../../schema-utils/entry-reference-util.ts'
 import { isObjectType } from 'graphql'
 import { EntryData } from '@commitspark/git-adapter'
 import { QueryMutationResolver } from '../types.ts'
 import { createError, ErrorCode } from '../../errors.ts'
+import { getCommitMessage } from '../commit-message.ts'
+import { commitWithRetry } from '../../../persistence/commit-with-retry.ts'
 
 function mergeData(
   existingEntryData: EntryData,
@@ -29,27 +34,41 @@ export const mutationUpdateResolver: QueryMutationResolver<EntryData> = async (
       {},
     )
   }
+  // narrowed type, as narrowing does not apply within the callback below
+  const entryType = context.type
+  const commitMessage = getCommitMessage(
+    args.commit,
+    'Update',
+    context.type.name,
+    args.id,
+  )
 
-  const existingEntry = await findByTypeId(context, context.type.name, args.id)
+  await commitWithRetry(context, async () => {
+    const existingEntry = await findByTypeId(
+      context,
+      context.type.name,
+      args.id,
+    )
+    await assertExpectedVersion(context, args.id, args.expectedVersion)
 
-  const mergedData = mergeData(existingEntry.data ?? null, args.data ?? null)
-  await validateEntryReferences(context.type, context, mergedData)
+    const mergedData = mergeData(existingEntry.data ?? null, args.data ?? null)
+    await validateEntryReferences(entryType, context, mergedData)
 
-  const commit = await context.gitAdapter.createCommit({
-    ref: context.branch,
-    parentSha: context.getCurrentHash(),
-    entries: [
-      {
-        id: existingEntry.id,
-        // only the type is written, which removes metadata no longer in use from existing entries
-        metadata: { type: existingEntry.metadata.type },
-        data: mergedData,
-        deletion: false,
-      },
-    ],
-    message: args.commitMessage,
+    return {
+      ref: context.branch,
+      parentSha: context.getCurrentHash(),
+      entries: [
+        {
+          id: existingEntry.id,
+          // only the type is written, which removes metadata no longer in use from existing entries
+          metadata: { type: existingEntry.metadata.type },
+          data: mergedData,
+          deletion: false,
+        },
+      ],
+      ...commitMessage,
+    }
   })
-  context.setCurrentHash(commit.commitHash)
 
   const updatedEntry = await findByTypeId(context, context.type.name, args.id)
   return { ...updatedEntry.data, id: updatedEntry.id }

package/src/graphql/resolvers/types.ts

@@ -8,6 +8,11 @@ import { EntryData } from '@commitspark/git-adapter'
 import { SearchHit } from '@commitspark/search-adapter'
 import { RecursiveArray } from './field-resolvers/types.ts'
 
+export interface CommitInput {
+  message?: string | null
+  body?: string | null
+}
+
 interface QueryMutationResolverContext extends ApolloContext {
   type: GraphQLNamedType
 }
@@ -15,7 +20,12 @@ interface QueryMutationResolverContext extends ApolloContext {
 export type QueryMutationResolver<ResultType> = GraphQLFieldResolver<
   unknown,
   QueryMutationResolverContext,
-  { id: string; data?: EntryData; commitMessage: string },
+  {
+    id: string
+    data?: EntryData
+    commit?: CommitInput | null
+    expectedVersion?: string | null
+  },
   Promise<ResultType>
 >
 
@@ -49,3 +59,10 @@ export type ReferencedByResolver = GraphQLFieldResolver<
   Record<string, never>,
   Promise<string[]>
 >
+
+export type VersionResolver = GraphQLFieldResolver<
+  EntryData & { id: string },
+  ApolloContext,
+  Record<string, never>,
+  Promise<string>
+>

package/src/graphql/schema-generator.ts

@@ -1,6 +1,7 @@
 import {
+  generateCommitInputType,
   generateQueriesAndMutations,
-  generateReferencedByFields,
+  generateEntryFields,
   generateSearchQuery,
   generateTypeNameQuery,
 } from './queries-mutations-generator.ts'
@@ -29,6 +30,7 @@ import {
   ReferencedByResolver,
   SearchQueryResolver,
   UnionTypeResolver,
+  VersionResolver,
 } from './resolvers/types.ts'
 import { EntryData } from '@commitspark/git-adapter'
 
@@ -63,7 +65,7 @@ export async function generateSchema(
   const generatedTypeNameQuery = generateTypeNameQuery()
   const generatedSearchQuery =
     context.searchAdapter !== undefined ? generateSearchQuery() : undefined
-  const generatedReferencedByFields = generateReferencedByFields(
+  const generatedEntryFields = generateEntryFields(
     schemaAnalyzerResult.entryDirectiveTypes,
   )
 
@@ -138,6 +140,7 @@ ${generatedSchemaRootTypeStrings}`
         | ContextInjectionResolver
         | FieldResolver
         | ReferencedByResolver
+        | VersionResolver
       >
     | UnionTypeResolverRecord
   > = {
@@ -157,21 +160,22 @@ ${generatedSchemaRootTypeStrings}`
       ...generatedObjectTypeFieldResolvers[typeName],
     }
   }
-  for (const field of generatedReferencedByFields) {
-    allGeneratedResolvers[field.typeName] = {
-      ...(allGeneratedResolvers[field.typeName] ?? {}),
-      [field.name]: field.resolver,
+  for (const entryFields of generatedEntryFields) {
+    allGeneratedResolvers[entryFields.typeName] = {
+      ...(allGeneratedResolvers[entryFields.typeName] ?? {}),
+      ...entryFields.resolvers,
     }
   }
 
   const typeDefs = [
     filteredOriginalSchemaString,
     generatedSchemaString,
+    generateCommitInputType(),
     generatedIdInputTypeStrings.join('\n'),
     generatedObjectInputTypeStrings.join('\n'),
     generatedUnionInputTypeStrings.join('\n'),
-    generatedReferencedByFields
-      .map((field) => field.typeExtensionString)
+    generatedEntryFields
+      .map((entryFields) => entryFields.typeExtensionString)
       .join('\n'),
     generatedSearchQuery?.typeDefinitionString ?? '',
   ].filter((typeDef) => typeDef.length > 0)

package/src/graphql/schema-validator.ts

@@ -2,6 +2,7 @@ import {
   getNamedType,
   GraphQLSchema,
   GraphQLUnionType,
+  isNonNullType,
   isObjectType,
   isScalarType,
   Kind,
@@ -59,8 +60,28 @@ function checkSearchableDirectiveOnlyOnStringFields(
   return ''
 }
 
+function checkEntryTypesHaveIdField(schema: GraphQLSchema): string {
+  for (const type of Object.values(schema.getTypeMap())) {
+    if (!isObjectType(type) || !hasDirective(type, ENTRY_DIRECTIVE_NAME)) {
+      continue
+    }
+    const idField = type.getFields()['id']
+    if (
+      idField === undefined ||
+      !isNonNullType(idField.type) ||
+      !isScalarType(idField.type.ofType) ||
+      idField.type.ofType.name !== 'ID'
+    ) {
+      return `Type "${type.name}" must have a field "id" of type "ID!" to use "@${ENTRY_DIRECTIVE_NAME}" directive.`
+    }
+  }
+
+  return ''
+}
+
 export function getValidationResult(schema: GraphQLSchema): string[] {
   const results = []
+  results.push(checkEntryTypesHaveIdField(schema))
   results.push(checkUnionMembersConsistentUseOfEntryDirective(schema))
   results.push(checkSearchableDirectiveOnlyOnStringFields(schema))
   return results.filter((result) => result !== '')

package/src/persistence/cache.ts

@@ -1,6 +1,7 @@
-import { Entry, GitAdapterError } from '@commitspark/git-adapter'
+import { Entry } from '@commitspark/git-adapter'
 import { ApolloContext } from '../client.ts'
 import { createError, ErrorCode } from '../graphql/errors.ts'
+import { callGitAdapter } from './git-adapter-call.ts'
 
 type Ref = string
 type ContentHash = string
@@ -14,6 +15,8 @@ type InflightEntries = Map<Ref, Promise<EntriesRecord>>
 export interface EntriesRecord {
   byId: Map<string, Entry>
   byType: Map<string, Entry[]>
+  // content hash of each entry as reported by the Git adapter, exposed to callers as entry version
+  hashById: Map<string, ContentHash>
 }
 
 interface CommitCacheRecord {
@@ -113,7 +116,9 @@ const fetchAndCacheEntries = async (
 
   const entriesById = new Map<string, Entry>()
   const entriesByType = new Map<string, Entry[]>()
+  const hashesById = new Map<string, ContentHash>()
   for (const { id, hash } of entryHashes) {
+    hashesById.set(id, hash)
     const entry: Entry = {
       id: id,
       ...(contentByHash.get(hash) as EntryContent),
@@ -128,6 +133,7 @@ const fetchAndCacheEntries = async (
     entriesRecord: {
       byType: entriesByType,
       byId: entriesById,
+      hashById: hashesById,
     },
     contentHashes: [...contentByHash.keys()],
   }
@@ -174,18 +180,6 @@ const removeUnreferencedContent = (
   }
 }
 
-const callGitAdapter = async <T>(operation: () => Promise<T>): Promise<T> => {
-  try {
-    return await operation()
-  } catch (err) {
-    if (err instanceof GitAdapterError) {
-      throw createError(err.message, err.code, {})
-    }
-    const message = err instanceof Error ? err.message : String(err)
-    throw createError(message, ErrorCode.INTERNAL_ERROR, {})
-  }
-}
-
 const getSchemaStringByRef = async (
   schemaCache: SchemaCache,
   cacheSize: number,

package/src/persistence/commit-with-retry.ts

@@ -0,0 +1,47 @@
+import {
+  CommitDraft,
+  ErrorCode as GitAdapterErrorCode,
+  GitAdapterError,
+} from '@commitspark/git-adapter'
+import { ApolloContext } from '../client.ts'
+import { callGitAdapter, toGraphQLError } from './git-adapter-call.ts'
+
+const MAX_COMMIT_ATTEMPTS = 3
+
+/**
+ * Commits a draft that `createDraft` validates against the current commit of the request, guaranteeing that the
+ * draft is only committed on top of the exact commit it was validated against.
+ *
+ * Git adapters only move a branch if it still points to `parentSha` and otherwise throw `CONFLICT`. As most adapters
+ * can only check this for the branch as a whole, any concurrent commit to the branch between reading and committing
+ * leads to `CONFLICT`, even if it changed unrelated entries. In this case, the current commit of the request is moved
+ * to the new branch head and the draft is created and validated again, including expected entry versions and
+ * references, so that only actual conflicts are reported to the caller.
+ *
+ * Errors thrown by `createDraft` are not retried, as the draft was validated against the latest known state.
+ */
+export const commitWithRetry = async (
+  context: ApolloContext,
+  createDraft: () => Promise<CommitDraft>,
+): Promise<void> => {
+  for (let attempt = 1; ; attempt++) {
+    const commitDraft = await createDraft()
+    try {
+      const commit = await context.gitAdapter.createCommit(commitDraft)
+      context.setCurrentHash(commit.commitHash)
+      return
+    } catch (err) {
+      const isConflict =
+        err instanceof GitAdapterError &&
+        err.code === GitAdapterErrorCode.CONFLICT
+      if (!isConflict || attempt >= MAX_COMMIT_ATTEMPTS) {
+        throw toGraphQLError(err)
+      }
+    }
+
+    const headCommitHash = await callGitAdapter(() =>
+      context.gitAdapter.getLatestCommitHash(context.branch),
+    )
+    context.setCurrentHash(headCommitHash)
+  }
+}

package/src/persistence/git-adapter-call.ts

@@ -0,0 +1,27 @@
+import { GitAdapterError } from '@commitspark/git-adapter'
+import { GraphQLError } from 'graphql'
+import { createError, ErrorCode } from '../graphql/errors.ts'
+
+/**
+ * Converts an error thrown by a Git adapter to a GraphQL error, keeping the error code of a `GitAdapterError`.
+ */
+export const toGraphQLError = (err: unknown): GraphQLError => {
+  if (err instanceof GitAdapterError) {
+    return createError(err.message, err.code, {})
+  }
+  const message = err instanceof Error ? err.message : String(err)
+  return createError(message, ErrorCode.INTERNAL_ERROR, {})
+}
+
+/**
+ * Runs a Git adapter operation and converts thrown errors to GraphQL errors.
+ */
+export const callGitAdapter = async <T>(
+  operation: () => Promise<T>,
+): Promise<T> => {
+  try {
+    return await operation()
+  } catch (err) {
+    throw toGraphQLError(err)
+  }
+}

package/src/persistence/persistence.ts

@@ -60,3 +60,53 @@ export async function findByTypeId(
 
   return entryById
 }
+
+/**
+ * Returns the version of an entry, which is the content hash of the entry reported by the Git adapter. It changes
+ * whenever the stored entry changes.
+ */
+export async function getEntryVersion(
+  context: ApolloContext,
+  id: string,
+): Promise<string> {
+  const entriesRecord = await context.repositoryCache.getEntriesRecord(
+    context,
+    context.getCurrentHash(),
+  )
+  const version = entriesRecord.hashById.get(id)
+  if (version === undefined) {
+    throw createError(`No entry with ID "${id}" exists.`, ErrorCode.NOT_FOUND, {
+      argumentName: 'id',
+      argumentValue: id,
+    })
+  }
+
+  return version
+}
+
+/**
+ * Throws `CONFLICT` if an expected version is given and the entry has a different version at the current commit of
+ * the request. This lets callers detect that an entry was changed by someone else since they read it, e.g. while a
+ * user was editing the entry, instead of overwriting these changes.
+ */
+export async function assertExpectedVersion(
+  context: ApolloContext,
+  id: string,
+  expectedVersion: string | null | undefined,
+): Promise<void> {
+  if (expectedVersion === undefined || expectedVersion === null) {
+    return
+  }
+  const currentVersion = await getEntryVersion(context, id)
+  if (currentVersion !== expectedVersion) {
+    throw createError(
+      `Entry with ID "${id}" has been changed: expected version "${expectedVersion}" but current version is ` +
+        `"${currentVersion}".`,
+      ErrorCode.CONFLICT,
+      {
+        argumentName: 'expectedVersion',
+        argumentValue: expectedVersion,
+      },
+    )
+  }
+}