executors: Version executor.Job

As part of RFC 751, changes to executor.Job most likely will break backwards compatibility with Sourcegraph (deserialization errors).

Multiple versions of executor.Job can be supported by using a “wrapper” struct that has an embedded interface. The interface is implemented by every different version of the Job.

Take the following example,

type JobWrapper struct {
    JobVersion
}

type JobVersion interface {
    Version() string
}

type JobV1 struct {
    Field1 string            `json:"field1"`
    Field2 map[string]string `json:"field2"`
    Field3 []string          `json:"field3"`
}

func (j JobV1) Version() string {
    return "v1"
}

With the JobWrapper, we can now deserialize multiple different versions of a job by implementing a custom UnmarshalJSON function.

func (j *JobWrapper) UnmarshalJSON(bytes []byte) error {
    var ver struct {
        Version string `json:"version"`
    }
    if err := json.Unmarshal(bytes, &ver); err != nil {
        return err
    }

    var jobVersion JobVersion
    switch ver.Version {
    case "":
        // Support the “old” version before versioning was introduced
        fallthrough
    case "v1":
        var v1 JobV1
        if err := json.Unmarshal(bytes, &v1); err != nil {
            return err
        }
        jobVersion = v1
    // ... other versions implemented
    default:
        return fmt.Errorf("unsupported version: %s", ver.Version)
    }
    j.JobVersion = jobVersion
    return nil
}

Done

Implement the versioning interface
Update documents to specify when to create a anew version
Add unit tests to cover changes
Do not break existing functionality

sourcegraph / sourcegraph-public-snapshot

executors: Version executor.Job #44445

Done