SpacetimeDB icon indicating copy to clipboard operation
SpacetimeDB copied to clipboard

Create `st_module` `module_version` column for module writers to manage semantic versioning

Open cloutiertyler opened this issue 1 year ago • 3 comments

Version the codegen and send that along the messages, modules, etc similar to:

API: 1.1.2

Also, when SATS encoding prepared this plus a hash of the original schema

[("1", AlgebraicType::I32)] == [API: 1.1.2, Hash: 0x1..]

so we can be sure the decoding match the supplied schema:

let original = [("1", AlgebraicType::I32); [AlgebraicValue::I32(1)] 
//imagine this was done in this specific ABI
let schema = api_1_1_2(original) == [API: 1.1.2, Hash: 0x1..]

let encoded = encode(original) == [API: 1.1.2, Hash: 0x1.., Data: 1]

//and the ABI break
let schema = api_1_0_1(original) == [API: 1.0.1, Hash: 0x1..]

let decoded = decode(schema, [AlgebraicValue::I32(1)]) != encoded

cloutiertyler avatar Jun 11 '24 14:06 cloutiertyler

Modules can be updated in the following ways:

  • Add a table: Client should not break, and should log a warning if it hears an update from a table it doesn't know about

  • Remove a table: Client should remove all rows from its table. That's it.

  • Add column: Client should not break, should ignore the column and log a warning if it hears an update to a column it doesn't know about. (This might not work because of SATS parsing).

  • Remove column: Client should break. We can't support this.

  • Add a reducer: Client should not break. It should just not call the new reducer.

  • Remove a reducer: Client should log a warning or error that the reducer is missing.

  • Add index: ??? TBD @gefjon might have info on this one in the future based on how we do indexes specified in the module API.

  • Remove index: This may break some clients based on @joshua-spacetime's proposal because some subscription queries which were valid are no longer valid.

cloutiertyler avatar Sep 09 '24 20:09 cloutiertyler

Notably, a change to the module which does not change the types in the API at all could still be a major version change. e.g.

Imagine if BitCraft had a drop item reducer which took the inventory index as a parameter, and then switched to being 1 indexed instead of 0 indexed, this is a major version change.

fn drop_item(ctx: Ctx, index) {
    if ctx.client_version.is_less_than("2.4.5") {
       
    } 
}

cloutiertyler avatar Sep 09 '24 21:09 cloutiertyler

We should add a string to st_module which is the module_version which is a string and must be formatted like semantic versioning string. It should be a string to allow for things like -beta etc.

Possibly taken from your rust Cargo.toml file for the module.

We also want to do: https://github.com/clockworklabs/SpacetimeDB/issues/1683

When publishing a new module we can also issue a warning if they user didn't update their module version but made breaking changes.

cloutiertyler avatar Sep 09 '24 21:09 cloutiertyler