howto: define command, query, projector and view

the following is actual for 2023.11.16

Commands & Queries

define args, unlogged args and results in SQL as TYPE
define commands and queries itselves in SQL in EXTENSION ENGINE BUILTIN section

define command and queries in go code in Resources specifying the handler only. Args, Unlogged Args and Results objects must have NullQName

SQL


TYPE CreateLoginParams (
Login text NOT NULL,
AppName text NOT NULL,
SubjectKind int32 NOT NULL,
WSKindInitializationData text(1024) NOT NULL,
ProfileCluster int32 NOT NULL
);

TYPE CreateLoginUnloggedParams ( Password text NOT NULL );

-- actually c.registrt.CreateLogin has no result, it is specified here for an example TYPE CreateLoginResult { Res text NOT NULL };

TYPE IssuePrincipalTokenParams ( Login text NOT NULL, Password text NOT NULL, AppName text NOT NULL );

TYPE IssuePrincipalTokenResult ( PrincipalToken text NOT NULL, WSID int64 NOT NULL, WSError text(1024) NOT NULL );

EXTENSION ENGINE BUILTIN ( COMMAND CreateLogin (CreateLoginParams, UNLOGGED CreateLoginUnloggedParams) RETURNS CreateLoginResult; QUERY InitiateResetPasswordByEmail (InitiateResetPasswordByEmailParams) RETURNS InitiateResetPasswordByEmailResult; );

### Go code
```golang
func Provide() {
    cfg.Resources.Add(istructsmem.NewCommandFunction(
        appdef.NewQName(RegistryPackage, "CreateLogin"),
        appdef.NullQName,
        appdef.NullQName,
        appdef.NullQName,
        execCmdCreateLogin,
    ))
    cfg.Resources.Add(istructsmem.NewQueryFunction(
        appdef.NewQName(RegistryPackage, "IssuePrincipalToken"),
        appdef.NullQName,
        appdef.NullQName,
        execQryIssuePrincipalToken(asp, itokens))
    )
}
func execCmdCreateLogin(args istructs.ExecCommandArgs) (err error) {
...
}
func execQryIssuePrincipalToken(ctx context.Context, args istructs.ExecQueryArgs, callback istructs.ExecQueryCallback) (err error) {
...
}

Views

define in SQL only

VIEW RecordsRegistry (
IDHi int64 NOT NULL,
ID ref NOT NULL,
WLogOffset int64 NOT NULL,
QName qname NOT NULL,
PRIMARY KEY ((IDHi), ID)
) AS RESULT OF RecordsRegistryProjector;

Projectors

define in SQL in EXTENSION ENGINE BUILTIN section

define in go code to provide the handler

EXTENSION ENGINE BUILTIN(
SYNC PROJECTOR RecordsRegistryProjector AFTER INSERT ON (CRecord, WRecord, ORecord) OR AFTER UPDATE ON (CRecord, WRecord) INTENTS(View(RecordsRegistry));
);

func Provide() {
registryProjector := func(partition istructs.PartitionID) istructs.Projector {
    return istructs.Projector{
        Name: appdef.NewQName(appdef.SysPackage, "RecordsRegistryProjector"),
        Func: provideRecordsRegistryProjector(cfg),
    }
}
cfg.AddSyncProjectors(registryProjector)
}
func recordsRegistryProjector(event istructs.IPLogEvent, st istructs.IState, intents istructs.IIntents) (err error) {
...
}

voedger / kb