Data.API.Changes

This module deals with validating API changelogs and migrating JSON data between different versions of a schema.

Documentation

migrateDataDump

Arguments

:: (Read db, Read rec, Read fld)

=> (API, Version)

Starting schema and version

-> (API, VersionExtra)

Ending schema and version

-> APIChangelog

Log of changes, containing both versions

-> CustomMigrations Object Value db rec fld

Custom migration functions

-> TypeName

Name of the dataset's type

-> DataChecks

How thoroughly to validate changes

-> Value

Dataset to be migrated

-> Either MigrateFailure (Value, [MigrateWarning])

Migrate a dataset from one version of an API schema to another. The data must be described by a named type, the name of which is assumed not to change.

The db, rec and fld types must be enumerations of all the custom migration tags in the changelog, as generated by generateMigrationKind.

migrateDataDump'

Arguments

:: (Read db, Read rec, Read fld)

=> (API, Version)

Starting schema and version

-> (API, VersionExtra)

Ending schema and version

-> APIChangelog

Log of changes, containing both versions

-> CustomMigrations Record Value db rec fld

Custom migration functions

-> TypeName

Name of the dataset's type

-> DataChecks

How thoroughly to validate changes

-> Value

Dataset to be migrated

-> Either MigrateFailure (Value, [MigrateWarning])

Validating changelogs

validateChanges

Arguments

:: (Read db, Read rec, Read fld)

=> (API, Version)

Starting schema and version

-> (API, VersionExtra)

Ending schema and version

-> APIChangelog

Changelog to be validated

-> CustomMigrations o v db rec fld

Custom migration functions

-> TypeName

Name of the dataset's type

-> DataChecks

How thoroughly to validate changes

-> Either ValidateFailure [ValidateWarning]

Check that a changelog adequately describes how to migrate from one version to another.

dataMatchesAPI :: TypeName -> API -> Value -> Either (ValueError, Position) ()

Check that a dataset matches an API, which is necessary for succesful migration. The name of the dataset's type must be specified.

data DataChecks

When to validate the data against the schema (each level implies the preceding levels):

Constructors

NoChecks

Not at all

CheckStartAndEnd

At start and end of the migration

CheckCustom

After custom migrations

CheckAll

After every change

Instances

Eq DataChecks

Methods

(==) :: DataChecks -> DataChecks -> Bool

(/=) :: DataChecks -> DataChecks -> Bool

Ord DataChecks

Methods

compare :: DataChecks -> DataChecks -> Ordering

(<) :: DataChecks -> DataChecks -> Bool

(<=) :: DataChecks -> DataChecks -> Bool

(>) :: DataChecks -> DataChecks -> Bool

(>=) :: DataChecks -> DataChecks -> Bool

max :: DataChecks -> DataChecks -> DataChecks

min :: DataChecks -> DataChecks -> DataChecks

Changelog representation

data APIChangelog

An API changelog, consisting of a list of versions with the changes from one version to the next. The versions must be in descending order (according to the Ord Version instance).

Constructors

ChangesUpTo VersionExtra [APIChange] APIChangelog

The changes from the previous version up to this version.

ChangesStart Version

The initial version

Instances

Eq APIChangelog

Methods

(==) :: APIChangelog -> APIChangelog -> Bool

(/=) :: APIChangelog -> APIChangelog -> Bool

Show APIChangelog

Methods

showsPrec :: Int -> APIChangelog -> ShowS

show :: APIChangelog -> String

showList :: [APIChangelog] -> ShowS

type APIWithChangelog = (API, APIChangelog)

data APIChange

A single change within a changelog

Constructors

ChAddType TypeName NormTypeDecl

ChDeleteType TypeName

ChRenameType TypeName TypeName

ChAddField TypeName FieldName APIType (Maybe DefaultValue)

ChDeleteField TypeName FieldName

ChRenameField TypeName FieldName FieldName

ChChangeField TypeName FieldName APIType MigrationTag

ChAddUnionAlt TypeName FieldName APIType

ChDeleteUnionAlt TypeName FieldName

ChRenameUnionAlt TypeName FieldName FieldName

ChAddEnumVal TypeName FieldName

ChDeleteEnumVal TypeName FieldName

ChRenameEnumVal TypeName FieldName FieldName

ChCustomType TypeName MigrationTag

ChCustomAll MigrationTag

Instances

Eq APIChange

Methods

(==) :: APIChange -> APIChange -> Bool

(/=) :: APIChange -> APIChange -> Bool

Show APIChange

Methods

showsPrec :: Int -> APIChange -> ShowS

show :: APIChange -> String

showList :: [APIChange] -> ShowS

PPLines APIChange

Methods

ppLines :: APIChange -> [String]

data VersionExtra

Represents either a released version (with a version number) or the version under development, which is newer than any release

Constructors

Release Version

DevVersion

Instances

Eq VersionExtra

Methods

(==) :: VersionExtra -> VersionExtra -> Bool

(/=) :: VersionExtra -> VersionExtra -> Bool

Ord VersionExtra

Methods

compare :: VersionExtra -> VersionExtra -> Ordering

(<) :: VersionExtra -> VersionExtra -> Bool

(<=) :: VersionExtra -> VersionExtra -> Bool

(>) :: VersionExtra -> VersionExtra -> Bool

(>=) :: VersionExtra -> VersionExtra -> Bool

max :: VersionExtra -> VersionExtra -> VersionExtra

min :: VersionExtra -> VersionExtra -> VersionExtra

Show VersionExtra

Methods

showsPrec :: Int -> VersionExtra -> ShowS

show :: VersionExtra -> String

showList :: [VersionExtra] -> ShowS

PP VersionExtra

Methods

pp :: VersionExtra -> String

showVersionExtra :: VersionExtra -> String

changelogStartVersion :: APIChangelog -> Version

The earliest version in the changelog

changelogVersion :: APIChangelog -> VersionExtra

The latest version in the changelog

Custom migrations

data CustomMigrations o v db ty fld

Custom migrations used in the changelog must be implemented in Haskell, and supplied in this record. There are three kinds:

• Whole-database migrations, which may arbitrarily change the API schema and the data to match;
• Type migrations, which may change the schema of a single type; and
• Single field migrations, which may change only the type of the field (with the new type specified in the changelog).

For database and type migrations, if the schema is unchanged, the corresponding function should return Nothing.

The db, ty and fld parameters should be instantiated with the enumeration types generated by generateMigrationKinds, which correspond to the exact set of custom migration tags used in the changelog.

Constructors

CustomMigrations

Fields

• databaseMigration :: db -> o -> Either ValueError o
• databaseMigrationSchema :: db -> NormAPI -> Either ApplyFailure (Maybe NormAPI)
• typeMigration :: ty -> v -> Either ValueError v
• typeMigrationSchema :: ty -> NormTypeDecl -> Either ApplyFailure (Maybe NormTypeDecl)
• fieldMigration :: fld -> v -> Either ValueError v

mkRecordMigration :: (Object -> Either ValueError Object) -> Value -> Either ValueError Value

Lift a custom record migration to work on arbitrary values

mkRecordMigration' :: (Record -> Either ValueError Record) -> Value -> Either ValueError Value

mkRecordMigrationSchema :: TypeName -> (NormRecordType -> Either ApplyFailure (Maybe NormRecordType)) -> NormTypeDecl -> Either ApplyFailure (Maybe NormTypeDecl)

Lift a schema change on record types to work on arbitrary type declarations

noDataChanges :: a -> Either ValueError a

Use for databaseMigration, typeMigration or fieldMigration to indicate that changes to the data are not required

noSchemaChanges :: a -> Either ApplyFailure (Maybe a)

Use for databaseMigrationSchema or typeMigrationSchema to indicate that the schema should not be changed

generateMigrationKinds :: APIChangelog -> String -> String -> String -> Q [Dec]

Generate enumeration datatypes corresponding to the custom migrations used in an API migration changelog.

type MigrationTag = String

Within the changelog, custom migrations are represented as strings, so we have less type-safety.

API normal forms

type NormAPI = Map TypeName NormTypeDecl

The API type has too much extra info for us to be able to simply compare them with (==). Our strategy is to strip out ancillary information and normalise into a canonical form, and then we can use a simple (==) compare.

Our normalised API discards most of the details of each type, keeping just essential information about each type. We discard order of types and fields, so we can use just associative maps.

data NormTypeDecl

The normal or canonical form for a type declaration, an APINode. Equality of the normal form indicates equivalence of APIs.

We track all types.

Constructors

NRecordType NormRecordType

NUnionType NormUnionType

NEnumType NormEnumType

NTypeSynonym APIType

NNewtype BasicType

Instances

Eq NormTypeDecl

Methods

(==) :: NormTypeDecl -> NormTypeDecl -> Bool

(/=) :: NormTypeDecl -> NormTypeDecl -> Bool

Show NormTypeDecl

Methods

showsPrec :: Int -> NormTypeDecl -> ShowS

show :: NormTypeDecl -> String

showList :: [NormTypeDecl] -> ShowS

NFData NormTypeDecl

Methods

rnf :: NormTypeDecl -> ()

PPLines NormTypeDecl

Methods

ppLines :: NormTypeDecl -> [String]

type NormRecordType = Map FieldName APIType

The canonical form of a record type is a map from fields to values...

type NormUnionType = Map FieldName APIType

...similarly a union is a map from fields to alternatives...

type NormEnumType = Set FieldName

...and an enum is a set of values.

apiNormalForm :: API -> NormAPI

Compute the normal form of an API, discarding extraneous information.

declNF :: Spec -> NormTypeDecl

Compute the normal form of a single type declaration.

Migration errors

data MigrateFailure

Constructors

ValidateFailure ValidateFailure

ValueError ValueError Position

Instances

Eq MigrateFailure

Methods

(==) :: MigrateFailure -> MigrateFailure -> Bool

(/=) :: MigrateFailure -> MigrateFailure -> Bool

Show MigrateFailure

Methods

showsPrec :: Int -> MigrateFailure -> ShowS

show :: MigrateFailure -> String

showList :: [MigrateFailure] -> ShowS

PPLines MigrateFailure

Methods

ppLines :: MigrateFailure -> [String]

type MigrateWarning = ValidateWarning

data ValidateFailure

Errors that may be discovered when validating a changelog

Constructors

ChangelogOutOfOrder

the changelog must be in descending order of versions

Fields

• vfLaterVersion :: VersionExtra
• vfEarlierVersion :: VersionExtra

CannotDowngrade

forbid migrating from one version to an earlier version

Fields

• vfFromVersion :: VersionExtra
• vfToVersion :: VersionExtra

ApiInvalid

an API uses types that are not declared

Fields

• vfInvalidVersion :: VersionExtra
• vfMissingDeclarations :: Set TypeName

ChangelogEntryInvalid

changelog entry does not apply

Fields

• vfSuccessfullyApplied :: [APITableChange]
• vfFailedToApply :: APIChange
• vfApplyFailure :: ApplyFailure

ChangelogIncomplete

changelog is incomplete (ie all entries apply ok but result isn't the target api)

Fields

• vfChangelogVersion :: VersionExtra
• vfTargetVersion :: VersionExtra
• vfDifferences :: Map TypeName (MergeResult NormTypeDecl NormTypeDecl)

Instances

Eq ValidateFailure

Methods

(==) :: ValidateFailure -> ValidateFailure -> Bool

(/=) :: ValidateFailure -> ValidateFailure -> Bool

Show ValidateFailure

Methods

showsPrec :: Int -> ValidateFailure -> ShowS

show :: ValidateFailure -> String

showList :: [ValidateFailure] -> ShowS

PPLines ValidateFailure

Methods

ppLines :: ValidateFailure -> [String]

data ValidateWarning

Instances

Show ValidateWarning

Methods

showsPrec :: Int -> ValidateWarning -> ShowS

show :: ValidateWarning -> String

showList :: [ValidateWarning] -> ShowS

data ApplyFailure

Errors that may occur applying a single API change

Constructors

TypeExists

for adding or renaming type

Fields

• afExistingType :: TypeName

TypeDoesNotExist

for deleting or renaming a type

Fields

• afMissingType :: TypeName

TypeWrongKind

e.g. it's not a record type

Fields

• afTypeName :: TypeName
• afExpectedKind :: TypeKind

TypeInUse

cannot delete/modify types that are still used

Fields

• afTypeName :: TypeName

TypeMalformed

type refers to a non-existent type

Fields

• afType :: APIType
• afMissingTypes :: Set TypeName

DeclMalformed

decl refers to a non-existent type

Fields

• afTypeName :: TypeName
• afDecl :: NormTypeDecl
• afMissingTypes :: Set TypeName

FieldExists

for adding or renaming a field

Fields

• afTypeName :: TypeName
• afTypeKind :: TypeKind
• afExistingField :: FieldName

FieldDoesNotExist

for deleting or renaming a field

Fields

• afTypeName :: TypeName
• afTypeKind :: TypeKind
• afMissingField :: FieldName

FieldBadDefaultValue

for adding a field, must be a default value compatible with the type

Fields

• afTypeName :: TypeName
• afFieldName :: FieldName
• afFieldType :: APIType
• afBadDefault :: DefaultValue

DefaultMissing

for adding a field to a table

Fields

• afTypeName :: TypeName
• afFieldName :: FieldName

TableChangeError

custom error in tableChange

Fields

• afCustomMessage :: String

Instances

Eq ApplyFailure

Methods

(==) :: ApplyFailure -> ApplyFailure -> Bool

(/=) :: ApplyFailure -> ApplyFailure -> Bool

Show ApplyFailure

Methods

showsPrec :: Int -> ApplyFailure -> ShowS

show :: ApplyFailure -> String

showList :: [ApplyFailure] -> ShowS

PPLines ApplyFailure

Methods

ppLines :: ApplyFailure -> [String]

data TypeKind

Constructors

TKRecord

TKUnion

TKEnum

TKNewtype

TKTypeSynonym

Instances

Eq TypeKind

Methods

(==) :: TypeKind -> TypeKind -> Bool

(/=) :: TypeKind -> TypeKind -> Bool

Show TypeKind

Methods

showsPrec :: Int -> TypeKind -> ShowS

show :: TypeKind -> String

showList :: [TypeKind] -> ShowS

PP TypeKind

Methods

pp :: TypeKind -> String

data MergeResult a b

Constructors

OnlyInLeft a

InBoth a b

OnlyInRight b

Instances

(Eq b, Eq a) => Eq (MergeResult a b)

Methods

(==) :: MergeResult a b -> MergeResult a b -> Bool

(/=) :: MergeResult a b -> MergeResult a b -> Bool

(Show b, Show a) => Show (MergeResult a b)

Methods

showsPrec :: Int -> MergeResult a b -> ShowS

show :: MergeResult a b -> String

showList :: [MergeResult a b] -> ShowS

data ValueError

Errors that can be discovered when migrating data values

Constructors

JSONError JSONError

Data doesn't match schema

CustomMigrationError String Value

Error generated during custom migration

InvalidAPI ApplyFailure

An API change was invalid

Instances

Eq ValueError

Methods

(==) :: ValueError -> ValueError -> Bool

(/=) :: ValueError -> ValueError -> Bool

Show ValueError

Methods

showsPrec :: Int -> ValueError -> ShowS

show :: ValueError -> String

showList :: [ValueError] -> ShowS

PPLines ValueError

Methods

ppLines :: ValueError -> [String]

prettyMigrateFailure :: MigrateFailure -> String

prettyValidateFailure :: ValidateFailure -> String

prettyValueError :: ValueError -> String

prettyValueErrorPosition :: (ValueError, Position) -> String