per-samuelsson / misc Goto Github PK

Need to learn that better.

Basics first, which is this issue. The setup is what's in the OP over at https://github.com/Starcounter/Starcounter/issues/3374.

Yes: this is not yet even a proposal. It's a first simple draft, just showing a direction I would get some basic feedback on before even considering it further.

So, main objective:

Better differentiate between stateful and stateless app programming models. A stateful web application will explicitly declare itself as such.

Traits at this point, and aims:

• Easier to understand / more intuitive what is being built
• Differentiate model with stateful apps and patching from underlying stateless APIs, i.e. Handle.GET etc.
• Unifies usage of Application.Current.Use and handle registration.
• Shield usage of session. The session should be a semi-advanced concept, and exposed on the app (not globally) when the developer need it: app.Session.

Program.cs
StatefulWebApplication.cs

Using RC4 tooling. Engine + unit tests + workloads for each distribution.

The very basics

With synonym

[Database] public class Person {
  public string Name { get; set; }
  public Person Friend;
}

[Database] public class BestFriend : Person {
  SynonymousTo("Friend")]
  public BestFriend Besty;
}

class Program {

    static void Main() {
        Db.Transact(() => {
            var besty = Db.SQL<BestFriend>("SELECT b FROM BasicWithSynonym.BestFriend b").FirstOrDefault();
            if (besty == null) {
                var bill = new BestFriend() { Name = "Bill" };
                var bull = new BestFriend() { Name = "Bull" };
                bill.Besty = bull;

                var piff = new BestFriend() { Name = "Piff" };
                var puff = new BestFriend() { Name = "Puff" };
                piff.Friend = puff;

                Console.WriteLine("Is Puff Piffs best friend? {0}", piff.Besty?.Equals(puff));
            }
        });
    }
}

When bound, we have metadata such as:

select * from Starcounter.Internal.Metadata.RawColumn c where c.Table.Name = 'bestfriend'

Doing this query produce expected result ("Bull") and below queryplan:

select f.Besty.Name from BasicWithSynonym.bestfriend f where f.Besty.Name = 'Bull'

Queryplan:

Tables(
 0 = BasicWithSynonym.BestFriend
 1 = BasicWithSynonym.BestFriend
)
Projection(
 0 = 
  StringPath(
   ObjectProperty(0, Besty)
   StringProperty(-1, Name)
  )
)
Join(
 Inner
 FullTableScan(
  BasicWithSynonym.BestFriend
  0
  LogicalValue(TRUE)
  Ascending
 )
 ReferenceLookup(
  1
  ObjectProperty(0, Besty)
  ComparisonString(
   Equal
   StringProperty(1, Name)
   StringLiteral(Bull)
  )
 )
)

Without synonym

[Database] public class Person {
  public string Name { get; set; }
  public Person Friend;
}

[Database] public class BestFriend : Person {
  public BestFriend Besty {
    get { return (BestFriend) Friend; }
    set { Friend = value; }
  }
}

class Program {

    static void Main() {
        Db.Transact(() => {
            var besty = Db.SQL<BestFriend>("SELECT b FROM BasicWithoutSynonym.BestFriend b").FirstOrDefault();
            if (besty == null) {
                var bill = new BestFriend() { Name = "Bill" };
                var bull = new BestFriend() { Name = "Bull" };
                bill.Besty = bull;

                var piff = new BestFriend() { Name = "Piff" };
                var puff = new BestFriend() { Name = "Puff" };
                piff.Friend = puff;

                Console.WriteLine("Is Puff Piffs best friend? {0}", piff.Besty?.Equals(puff));
            }
        });
    }
}

When bound, we have metadata such as:

select c.* from Starcounter.Internal.Metadata.RawColumn c where c.Table.FullName = 'BasicWithoutSynonym.BestFriend'

And query:

select f.Name from BasicWithoutSynonym.bestfriend f where f.Besty.Name = 'Bull'

Queryplan

Tables(
 0 = BasicWithoutSynonym.BestFriend
 1 = BasicWithoutSynonym.BestFriend
)
Projection(
 0 = 
  StringProperty(0, Name)
)
Join(
 Inner
 FullTableScan(
  BasicWithoutSynonym.BestFriend
  0
  LogicalValue(TRUE)
  Ascending
 )
 ReferenceLookup(
  1
  ObjectProperty(0, Besty)
  ComparisonString(
   Equal
   StringProperty(1, Name)
   StringLiteral(Bull)
  )
 )
)

Note: starx is a working name. The final name of the tool is TBD.

We are starting in empty src\app.

Basics

dotnet new mvc
dotnet add package Starcounter.Nova --version 1.2.3

The above creates a standard MVC project and adds a reference to Nova stack. After this, developer can start coding and get a feeling of our API.

But...

dotnet run

Exception: Unable to connect to `[app_name]\default`. 
Database config not found. Have you forgot to run 'starx init'? 

See https://starcounter.io/getting-started

Install tooling

dotnet new tool-manifest
dotnet tool install starx --version 1.2.3

The above install starx as a .NET Core 3.0 local tool. The tool is versioned, and bring down with it the entire Starcounter runtime, i.e. a version of the appropriate Bluestar package. This directory - and hence the app - now have a manifest file that ties the app to a certain version of the tool.

Still though...

dotnet run

Exception: Unable to connect to `[app_name]\default`. 
Database config not found. Have you forgot to run 'starx init'? 

See https://starcounter.io/getting-started

Initialize database

dotnet tool run starx init <optional: data path, default: bin\data>

Running starx with the init argument does this:

1. Creates bin\data folder
2. Creates bin\data\default, to host default database.
3. Creates db.default.config

After this, directory will look conceptually like:

\bin
  app.exe
\bin\data\default
  default.cfg
Program.cs
Project.csproj
db.default.config

Now the error is something else:

dotnet run

Exception: Unable to connect to `[app_name]\default`.
Database is not running. Have you forgot to run 'starx start'? 

See https://starcounter.io/getting-started

What happened was that the app/host now found db.default.config (because no database config was explicitly given, it looked for db.default.config in the current working directory. This can be overridden in environment.

In that file, it looked for the UUID the starx tool has generated and stored in there when the default database was created (or, alternatively, if it's better to store path to database file + tool version, and every consumer generate UUID on the fly). It tried to connect using that, but failed because database was not started.

Starting database

dotnet tool run starx start <optional: data name, default: default>

The starx tool now simply works as the host does, and reads the db.default.config file in the same manner as the above, but instead invokes starting of scdata with the UUID in there. Because of how the restore works, starx will be bundled with the Bluestar natives and the tool can easily resolve their path in a predictable way.

Voila:

dotnet run
Hello world from Starcounter Nova.

Unit test

First we create the unit test project.

cd ..\..
mkdir app.test
cd app.test
dotnet new xunit
dotnet add reference ..\src\app\app.proj

As part of one time test setup when tests are executed, we connect to the database using the same config that belong to the app, e.g. db.default.config. Alternatively, we can grab the UUID from there and simply store it in our tests. Not sure about the best approach here, so the exact details need to be worked out.

Summary

The entire getting started:

dotnet new mvc
dotnet add package Starcounter.Nova --version 1.2.3

dotnet new tool-manifest
dotnet tool install starx --version 1.2.3

dotnet tool run starx init
dotnet tool run starx start

dotnet run

To be decided

TBD 1: We can, in version 2, have app/host try to start database if it can't connect, using library shared between host and the tool. But that's an opt-in. The config model is prepared for that at least.
TBD 2: Consider publish story. Do we want to publish the tool manifest and/or config?
TBD 3: We can consider making starx init implicit, i.e. assure it runs on the first usage. And/or have init start the default database implicitly.
TBD 4: Maybe we don't want init, but rather starx newdb or something.
TBD 5: We could consider delivering starx tool as part of Bluestar package instead, and have application directly reference Bluestar, but I think the propsed design is better.

What you do

You install the latest 2.3+ version from http://downloads.starcounter.com/download. You run the setup with all default values.

** WORK IN PROGRESS **

What happens

Installation folder

All Starcounter binary files are stored under C:\Program Files\Starcounter:

Program Files\Starcounter:
[Image]

Server repository

This is where your data reside. It also include all configuration. And logs.

Starcounter Web Administrator

localhost:8181. Is there a desktop icon? Here you see all your databases and the running applications. Also, you can see the log and make queries.

Visual Studio

If you have Visual Studio installed, there will now be a new project type: Starcounter Application. These applications are hosted by the database.

%StarcounterBin%

How the installation reference the server repository

Under \configuration

Processes - what is the server?

Windows service or not.

Command-line tools

Complement the web interface.