fission-suite / webnative-elm / Webnative

Interface for webnative, version 0.24 and up.

  1. Getting Started
  2. Ports
  3. Authorisation
  4. Authentication
  5. Filesystem
  6. Miscellaneous

Getting Started

init : Permissions -> Request

🚀 Start here

Check if we're authenticated, process any lobby query-parameters present in the URL, and initiate the user's filesystem if authenticated (can be disabled using initWithOptions).

See loadFileSystem if you want to load the user's filesystem yourself. NOTE, this only works on the main/ui thread, as it uses window.location.

See the README for an example.

initWithOptions : InitOptions -> Permissions -> Request

Initialise webnative, with options.


type alias InitOptions =
{ autoRemoveUrlParams : Basics.Bool
, loadFileSystem : Basics.Bool 
}

Options for initWithOptions.

Setting autoRemoveUrlParams to True causes webnative to automatically remove the query parameters from the lobby.

Setting loadFileSystem to False disables the automatic loading of the filesystem during init.

defaultInitOptions : InitOptions

Default InitOptions.

initialise : Permissions -> Request

Alias for init.

initialize : Permissions -> Request

Alias for init.

Ports

Data flowing through the ports. See 🚀 in the decodeResponse example on how to handle the result from init.

decodeResponse : (String -> Result String tag) -> Response -> DecodedResponse tag

Decode the result, the Response, from our Request. Connect this up with webnativeResponse subscription port.

subscriptions =
    Ports.webnativeResponse GotWebnativeResponse

And then in update use this function.

GotWebnativeResponse response ->
  case Webnative.decodeResponse tagFromString response of
    -----------------------------------------
    -- 🚀
    -----------------------------------------
    Webnative ( Initialisation state ) ->
      if Webnative.isAuthenticated state then
        loadUserData
      else
        welcome

    -----------------------------------------
    -- 💾
    -----------------------------------------
    Wnfs ReadHelloTxt ( Utf8Content helloContents ) ->
      -- Do something with content from hello.txt

    Wnfs Mutation _ ->
      ( model
      , { tag = PointerUpdated }
          |> Wnfs.publish
          |> Ports.webnativeRequest
      )

    -----------------------------------------
    -- 🥵
    -----------------------------------------
    -- Do something with the errors,
    -- here we cast them to strings
    WebnativeError err -> Webnative.error err
    WnfsError err -> Wnfs.error err

See the README for the full example.


type DecodedResponse tag
    = Webnative Artifact
    | WebnativeError Error
    | Wnfs tag Wnfs.Artifact
    | WnfsError Wnfs.Error

Request, or response, context.


type Artifact
    = Initialisation State
    | NoArtifact NoArtifact

Artifact we receive in the response.


type NoArtifact
    = LoadedFileSystemManually
    | RedirectingToLobby
    | SignedOut

Not really artifacts, but kind of. Part of the Artifact type.


type alias Request =
{ context : String
, tag : String
, method : String
, arguments : List Json.Encode.Value 
}

Request from webnative.


type alias Response =
{ context : String
, error : Maybe String
, tag : String
, method : String
, data : Json.Encode.Value 
}

Response from webnative.


type Error
    = DecodingError String
    | InvalidMethod String
    | InsecureContext
    | JavascriptError String
    | UnsupportedBrowser

Possible errors.

error : Error -> String

Error message.

context : String

Request/Response context.

Authorisation

redirectToLobby : RedirectTo -> Permissions -> Request

Redirect to the authorisation lobby.


type RedirectTo
    = CurrentUrl
    | RedirectTo Url

Where the authorisation lobby should redirect to after authorisation.


type alias AppPermissions =
{ creator : String
, name : String 
}

Application permissions.


type alias FileSystemPermissions =
{ private : BranchFileSystemPermissions
, public : BranchFileSystemPermissions 
}

Filesystem permissions.

```elm
import Webnative.Path as Path

{ private =
    { directories = [ Path.directory [ "Audio", "Mixtapes" ] ]
    , files = [ Path.file [ "Audio", "Playlists", "Jazz.json" ] ]
    }
, public =
    { directories = []
    , files = []
    }
}
```


type alias BranchFileSystemPermissions =
{ directories : List (Path Path.Directory)
, files : List (Path Path.File) 
}

Filesystem permissions for a branch.

This is reused for the private and public permissions.


type alias Permissions =
{ app : Maybe AppPermissions
, fs : Maybe FileSystemPermissions 
}

Permissions to ask the user. See AppPermissions and FileSystemPermissions on how to use these.

Authentication

isAuthenticated : State -> Basics.Bool

Are we authenticated?

leave : Request

Leave the app and go the lobby. Removes all traces of the user. Use signOut instead if you don't want the redirect.

signOut : Request

Removes all traces of the user. Use leave instead if you want to go to the lobby immediately so the user can sign out there as well, if needed.


type State
    = NotAuthorised
    | AuthSucceeded AuthSucceededState
    | AuthCancelled AuthCancelledState
    | Continuation ContinuationState

Initialisation state, result from init.


type alias AuthSucceededState =
{ newUser : Basics.Bool
, throughLobby : Basics.Bool
, username : String 
}

State attributes when auth has succeeded.


type alias AuthCancelledState =
{ cancellationReason : String
, throughLobby : Basics.Bool 
}

State attributes when auth was cancelled.


type alias ContinuationState =
{ newUser : Basics.Bool
, throughLobby : Basics.Bool
, username : String 
}

State attributes when continueing a session.

Filesystem

loadFileSystem : Permissions -> Request

Load in the filesystem manually.