New lix client api

[janfjohannes]

We will have to do changes to the lix client api in order to facilitate things like userinfo and login/logout, which would not live on the repo level, but it would be awkward to have to supply the info where lix is running in every api call.

my first proposa:

instead of

const newRepo = await openRepository(`${host}/${owner}/${repository}`, {
                    nodeishFs: createNodeishMemoryFs(),
                    corsProxy: publicEnv.PUBLIC_GIT_PROXY_BASE_URL + publicEnv.PUBLIC_GIT_PROXY_PATH,
                })

the new api would look like this:

const lixClient = await createLixClient({
                    lixUrl: publicEnv.PUBLIC_LIX_URL,
                })

const newRepo = await lixClient.openRepository(`${host}/${owner}/${repository}`, {
                    nodeishFs: createNodeishMemoryFs()
                })

[samuelstroschein]

An alternative could be an auth object which optionally gets passed to openRepository().

const auth = await authenticate()

const repo = await openRepository(`https://lix.inlang.com/git/${host}/{owner}/{repository}`, { nodeishFs, auth })

Pros

• opening a local repository requires no auth, why should we force createClient then?
• tree shakable auth and other modules (if auth is not used -> not bundled)

Cons

• ?

[samuelstroschein]

@janfjohannes [in the future] the openRepository should likely include the full URI and not derive the base URI from "the client". Keep it simple, make it explicit

[samuelstroschein]

Thinking out loud here. Seems to me that the auth object should be embedded in the repo itself. Depending on the environment, a different auth object/module is used.

• no duplicate "host" address. openRepostiry with the uri, done.
• one entry point openRepository for a lix client, extended with modules.

type Auth = {
  // onSignIn is called by openRepository when sign is is required
  // can open a website to login, a custom flow whatever. 
  // async once resolved, open repository will try to open the repository again
  onSignIn: (uri) => Promise<Token>
} 

// in a web app
const repo = await openRepository("https://lix.inlang.com/...", { 
  nodeishFs, auth: webApp
})

// node server environment

const repo = await openRepository("https://lix.inlang.com/...", { 
  nodeishFs, auth: nodeServer
})

// cli environment which requires prompting the user and setting the token somewhere
const repo = await openRepository("https://lix.inlang.com/...", { 
  nodeishFs, auth: cliAuth
})

// list goes on

[samuelstroschein]

I think we can go either way. Let's not make a big deal out of this decision. I slightly prefer the auth object passed to open repository direction as openRepository is already the client. A client that get's optional objects like auth, fs, and more as required by the to be opened repository.

[janfjohannes]

i am not sure we should burden the apps to carry around auth or user objects and pass that to apis that need them.

also another issue is that the login is depending on the environment not directly acccesible. for example in browser environments the token is inside a http only cookie so it would be not obvious how to handle the auth object (eg. you would still be logged in if you do not pass the object to the api and if you login again and save both objects you could not use two auth objects simultaneously as you would expect ..). if the auth is jsut internal state of the lixClient this would be much simpler to reason about.

the auth api with my proposal would be

explicit:

const lixClient = await createLixClient({
                    lixUrl: publicEnv.PUBLIC_LIX_URL,
                })
                
                const user = await lixClient.getUser()
                if (!user) {
                   await lixClient.login() // only required if you want to do things that require a login or further rights, you could locally open a public repo
                } 

const newRepo = await lixClient.openRepository(`${host}/${owner}/${repository}`, {
                    nodeishFs: createNodeishMemoryFs()
                })

implicit:

const lixClient = await createLixClient({
                    lixUrl: publicEnv.PUBLIC_LIX_URL,
                    // something like this could automatically trigger login() 
                    // when an action is not possible anonymous, but would until such action is tried login could be postponed
                    autoLogin: true 
                })
           

const newRepo = await lixClient.openRepository(`${host}/${owner}/${repository}`, {
                    nodeishFs: createNodeishMemoryFs()
                    
                })

[samuelstroschein]

createLixClient/ a one stop auth solutoin won't work for the different environments that lix is running in (browser, node, server, "edge", ...). See https://github.com/orgs/inlang/discussions/1386#discussioncomment-7062768

[janfjohannes]

auth can still be pluggable and configurable, i wanted to show more that its important to give an app control over how and when to login and that would be very intuitive with this api. i am not sure where i would even call .login() with a auth object design...

[samuelstroschein]

i am not sure we should burden the apps to carry around auth or user objects and pass that to apis that need them.

Hm. The auth module/object only needs to be passed to openRepository.

const auth = await authenticate()
const repo = await openRepository(`https://lix.inlang.com/git/${host}/{owner}/{repository}`, { nodeishFs, auth })

I am wary of createLixClient because:

1. some apps don't need auth. we will bundle features in the client that are not required.
2. The auth differs per environment.
3. You are defining two endpoints. First, lixUrl and second repositortUrl. In reality, the endpoint is only one: the repository URI (server) that a repository can be opened from and a user authenticated against.

My proposal of passing modules as required to open the repository seems to increase the flexibility of a lix client and ease maintenance.

• auth modules are separate packages, imported as required
• we avoid the risk of bundling everything into a client which will a) make the client big b) is unmodular which is important given that lix runs in many different environments

The code below is essentially your proposal except that the auth module doesn't return a lix client but an auth object which can be passed to openRepository.

import { webAppLogin } from "@lix-js/auth"

const user = await webAppLogin()
const repo = await openRepository("https://lix.inlang.com/git/github.com/inlang/monorepo", {
  nodeishFs, 
  auth: user
})

// or server side

import { nodeAuth } from "@lix-js/auth"

const user = await nodeAuth()
const repo = await openRepository("https://lix.inlang.com/git/github.com/inlang/monorepo", {
  nodeishFs, 
  auth: user
})

[samuelstroschein]

@janfjohannes let's have a call tmr

[martin-lysk]

My 2 ct's on this topic:

Consider multiple "remotes"

With the current approach a repository is bound to an uri. I would challange this because with the goal to have an offline first system with remotes doing distribution in the next steps it's not unlikely that one repository - cloned or created locally - eventually has multiple remotes - like the remotes concept of git.

Why I bring this up here:
An authentication is most likely bound to a remote not to a repository. The same is true for the uri.

Introduce a class - provider or host that contains auth and a provider could become a reference of a remote

Provider or hosts should be a separate object independend from repositories - If I use the inlang editor I see two scenarios:

1. the one we implemented now - one passes a uri pointing to one specific repository
2. a future version where i log into the editor using my github account - or later have my github account connected to my lix account and be able to select the repo i want to start using the editor for from a list of my repos

By separating Provider from repo - this would be possible. I could than clone a repo using the provider i have configured.

[janfjohannes]

ok got a new proposal, please keep in mind this does not have to be anything final or super flexible we just need a good structure to move on with the restructuring, this will certainly change again when we build our real auth system and permissions. think of this as something in between the current hard coded auth in the editor and the final lix api.

this is basically samuels proposal with slightly different auth object in a browser context, as it otherwise wont work for http only cookies where auth is just an inaccessible hidden state of the browser and would lead to misconceptions how the object would behave. Also getUser should be seperate from the login as this requires requests for user data which might not be required.

in browser

  import { browserAuth,  openRepository } from "@lix-js/client"
  const auth = browserAuth({ lixUrl: 'https://lix.inlang.com' })
  // auth is optional, creating a lixclient explicitly is not required anymore you can directly call openRepository for anon things
  const user = await auth.getUser()
  if (!user?.loggedIn) {
    await auth.login()
  }

  const repo = await openRepository("https://lix.inlang.com/git/github.com/inlang/monorepo", {
    nodeishFs,
    auth
  })

  await auth.logout()

on server

 import { openRepository, tokenAuth } from "@lix-js/client"
  const auth = tokenAuth({token:'whatever', settings: ...})
  const repo = await openRepository("https://lix.inlang.com/git/github.com/inlang/monorepo", {
    nodeishFs,
    auth
  })

[samuelstroschein]

Perfect! Exactly what I had in mind. Import the auth module you need, if needed at all! :)

[janfjohannes]

@samuelstroschein ping me when you read the last proposal and have a minute, maybe we can make a decision in around