diff --git a/NOTES b/NOTES index 137507c..885520a 100644 --- a/NOTES +++ b/NOTES @@ -15,6 +15,12 @@ - User authorization API DONE: +>>v0.7.6<< +- Fix string message (remote) #242 +- Proxy (Set proxy / session API) #155 #169 +- Remote (Internal IPC Mechanism) +- Fix CloseDevTools #234 + >>v0.7.5<< - ThrustWindow and DevTools #205 - Input support for file and color #208 diff --git a/README.md b/README.md index 11011b1..d9fc51d 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,307 @@ -Thrust -====== +#### DEPRECATED - This package is no longer supporter or maintained. -The require-able cross-platform native application framework based on Chromium's -content module, Thrust lets you distribute nodeJS, Go or Python cross-plaform -GUI apps through their native package managers. -### General information -- [Wiki homepage](https://github.com/breach/thrust/wiki) +![Logo Thrust](http://i.imgur.com/IviZAGZ.png) -### Documentation +**Chromium-based cross-platform / cross-language application framework** -- Coming Soon +*Thrust is `require/import`-able, it lets you distribute NodeJS, Go or Python GUI apps directly +through their native package managers.* -### Getting Involved +Thrust is based on Chromium's Content Module and is supported on Linux, MacOSX and Windows: -- Mailing list: [breach-dev@googlegroups.com](https://groups.google.com/d/forum/breach-dev) -- IRC Channel: #breach on Freenode +![Cross-Platform Screenshots](http://i.imgur.com/7K98jyW.png) +*Screenshot of Thrust Getting Started example running on each major platform.* +To better understand what Thrust can do, check out **[JankyBrowser](https://gist.github.com/morganrallen/f07f59802884bcdcad4a)** by +@morganrallen, the cross-platform browser that fits in a gist: +``` +npm install -g \ + https://gist.github.com/morganrallen/f07f59802884bcdcad4a/download +``` + +#### Table of Contents +- [Language bindings](#language-bindings) + - [NodeJS](#nodejs) + - [Go](#go) + - [Python](#python) + - [Scala](#scala) + - [Clojure](#clojure) + - [Perl](#perl) +- [API Reference](#api-reference) +- [Architecture](#architecture) +- [Community](#community) + - [Request for API](#request-for-api) + - [List of Thrust Users](#list-of-thrust-users) + - [Thrust 7.5k Contest](#thrust75k-contest) + - [Getting Involved](#getting-involved) +- [Features & Roadmap](#features--roadmap) +- [Building Thrust from Sources](#building-thrust-from-sources) + +*** +## Language bindings + +Thrust's binary distribution exposes its API on the standard IO and language + specific library packages automatically download the binary distribution at +installation. Thrust is based on Chromium's content module and uses web-pages +as its GUI. + +All these Getting Started example work as is on each major platform (MacOSX, +Windows, Linux) + +### NodeJS +##### Getting Started + +First install with `npm install node-thrust` + +```Javascript +require('node-thrust')(function(err, api) { + api.window({ root_url: 'https://google.com' }).show(); +}); +``` + +##### Library + +- **node-thrust** [breach/node-thrust](https://github.com/breach/node-thrust/) + +### Go + +##### Getting Started + +First download with `go get -u github.com/miketheprogrammer/go-thrust/` + +```Go +``` +package main + +import ( + "github.com/miketheprogrammer/go-thrust/lib/dispatcher" + "github.com/miketheprogrammer/go-thrust/lib/spawn" + "github.com/miketheprogrammer/go-thrust/lib/bindings/window" + "github.com/miketheprogrammer/go-thrust/lib/commands" +) + +func main() { + spawn.Run() + size := commands.SizeHW{} + opts := window.Options{ + RootUrl: "http://google.com", + Size: size, + Title: "Demo window", + HasFrame: true, + } + thrustWindow := window.NewWindow(opts) + thrustWindow.Show() + thrustWindow.Maximize() + thrustWindow.Focus() + dispatcher.RunLoop() +} + +##### Library + +- **go-thrust**: [miketheprogrammer/go-thrust](https://github.com/miketheprogrammer/go-thrust) + +### Python + +##### Getting Started + +First install with `pip3 install pythrust [--user]` (requires Python3) + +```Python +import asyncio, pythrust + +loop = asyncio.get_event_loop() +api = pythrust.API(loop) + +asyncio.async(api.spawn()) +asyncio.async(api.window({ 'root_url': 'http://google.com' }).show()) + +loop.run_forever() +``` + +##### Library + +- **pythrust** [breach/pythrust](https://github.com/breach/pythrust/) + +### Scala + +##### Getting Started + +Include scala-thrust jar on your classpath. (Add to lib in your project.) + +```Scala +import scala.concurrent.ExecutionContext.Implicits.global +import com.github.eklavya.thrust._ + +object Main extends App { + Window.create("http://google.com").foreach { w => + w.show + w.maximize + w.openDevtools + w.focus(true) + w.onBlur(() => println("we were blurred")) + w.onFocus(() => println("we were focused")) + Menu.create("MyMenu").foreach { m => + val i = MenuItem("Item1", _ => println("Item1 was clicked")) + m.addItem(i) + m.popup(w) + } + } +} +``` + +##### Library + +- **scala-thrust** [eklavya/scala-thrust](https://github.com/eklavya/scala-thrust/) + +### Clojure + +##### Getting Started + +- [Installation](https://github.com/solicode/clj-thrust#installation) +- [Sample Project](https://github.com/solicode/clj-thrust#sample-project) + +```clojure +(ns my-app.core + (:require [clj-thrust.core :refer [create-process destroy-process]] + [clj-thrust.window :as w])) + +(let [process (create-process) ; `create-process` also takes path to Thrust directory + window (w/create-window process + :root-url "http://localhost:8080" ; URL to your web app + :size {:width 400 :height 300})] + (w/listen-closed window + (fn [e] + (destroy-process process))) ; Optionally call `(System/exit 0)` here. + (w/show window) + (w/focus window true)) +``` + +##### Library + +- **clj-thrust** [solicode/clj-thrust](https://github.com/solicode/clj-thrust) + +### Perl + +##### Getting Started + +Install with `cpanm Thrust [--sudo]` + +Simple command line test: + +``` +perl -MThrust -e 'Thrust->window->show->maximize->open_devtools->run' +``` + +Basic program + +```Perl +use Thrust; + +my $t = Thrust->new; + +my $w = $t->window( + root_url => 'data:text/html,Hello World!', + title => 'My App', + size => { width => 800, height => 600 }, + ); + +$w->on(closed => sub { exit }); + +$w->show; + +$t->run; ## enter event loop +``` + +##### Library + +- [metacpan](https://metacpan.org/pod/Thrust) +- [github](https://github.com/hoytech/Thrust) + + +*** +## API Reference + +The API reference as well as links to specific language bindings documentations +are availble in the [docs/](https://github.com/breach/thrust/tree/master/docs) + directory. + +*** +## Architecture + +``` +[Thrust Architecture] + + (Platform) [stdio] (Your Implementation) + + # + +--------------+ # +-----------------------+ | + | Cocoa / Aura | # +---| win3: (HTML/JS) | | + +-------+------+ # | +-----------------------++ | + | # +--| win2: (HTML/JS) | | cli ++------------+ +-------+------+ # | +-----------------------++ | +| +-+ thrust (C++) +-------+-+ win1: (HTML/JS) | | +| ContentAPI | +-------+------+ # +-----------------------+ | +| | | # | (TCP/FS) +| (Blink/v8) | +-------+------+ # +-----------------------+ | +| | + JSON RPC srv +---------+ Client App (any Lang) | | srv ++------------+ +--------------+ # +-----------------------+ | + # +``` + +*** +## Community + +##### Request for API + +- List of API needed by various projects on Thrust: +[Request for API](https://github.com/breach/thrust/wiki/Request-for-API) + +##### List of Thrust Users + +- List of people relying on Thrust: +[List of Thrust Users](https://github.com/breach/thrust/wiki/List-of-Thrust-Users) + +##### Getting Involved +No longer maintained actively. + +*** +## Features & Roadmap + +- [x] **window creation** create, show, close resize, minimize, maximize, ... +- [x] **node.js, go** node.js and go bindings libraries +- [x] **window events** close, blur, focus, unresponsive, crashed +- [x] **cross-platform** equivalent support on `MacOSX`, `Windows` and `Linux` +- [x] **sessions** off the record, custom storage path, custom cookie store +- [x] **kiosk** kiosk mode +- [x] **application menu** global application menu (MacOSX, X11/Unity) +- [x] **webview** webview tag (secure navigation, tabs management) +- [x] **frameless** frameless window and draggable regions +- [x] **python** python bindings library +- [x] **remote** thrust specific IPC mechanism for client/server communication +- [x] **proxy** enable traffic proxying (Tor, header injection, ...) +- [ ] **tray icon** tray icon native integration +- [ ] **protocol** specific protocol registration (`file://`, ...) + +*** +## Building Thrust from Sources + +You will generally don't need to build thrust yourself. A binary version of +thrust should be automatically fetched by the library you're reyling on at +installation. + +To build thrust, you'll need to have `python 2.7.x` and `git` installed. You can +then boostrap the project with: +``` +./scripts/boostrap.py +``` + +Build both the `Release` and `Debug` targets with the following commands: +``` +./scripts/update.py +./scripts/build.py +``` + +Note that `bootstrap.py` may take some time as it checks out `brightray` and +downloads `libchromiumcontent` for your platform. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..39f1341 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,33 @@ + +A typical Thrust app is composed of two main components. The platform code +which is language specific and calls into one of Thrust's language binding, +and the HTML5 client code which is executed by Thrusts windows. + +The platform code is generally in charge of serving the client code locally and +provide an API for it to interact with. As the platform code is language +specific, the API reference only describe objects and available methods, using +a pseudocode format, as exposed by Thrust standard I/O API for language bindings +to interact with. Please refer to your specific language bindings for a more +specific documentation and syntax. + +### API Reference + +Platform code objects: + +- [window](api/window.md) +- [session](api/session.md) +- [menu](api/menu.md) + +Client code modules: + +- remote (coming soon) + +Client custom DOM elements: + +- [`` tag](api/webview.md) + +### Language Bindings Documentation and Guides + +- [node-thrust](https://github.com/breach/node-thrust) +- [go-thrust](https://github.com/miketheprogrammer/go-thrust/tree/master/doc) +- [pythrust](https://github.com/breach/pythrust) diff --git a/docs/api/menu.md b/docs/api/menu.md new file mode 100644 index 0000000..e5dd83b --- /dev/null +++ b/docs/api/menu.md @@ -0,0 +1,95 @@ +menu +==== + +The `menu` object provides an API to create native global application menu +(MacOSX and X11/Unity only) and native context menus. + +Window specific menus on other platform are meant to be handled using client +side code. + +#### Constructor + +#### Event: `execute` + +- `command_id` the command id of the item that was clicked +- `event_flags` event flag integer + +Emitted when a menu item is clicked + +#### Method: `add_item` + +- `command_id` the label command id (see `execute`) +- `label` the item label + +Adds a standard item to the menu + +#### Method: `add_check_item` + +- `command_id` the label command id (see `execute`) +- `label` the item label + +Adds a check item to the menu + +#### Method: `add_radio_item` + +- `command_id` the label command id (see `execute`) +- `label` the item label +- `group_id` radio group + +Adds a radio item to the menu + +#### Method: `add_separator` + +Adds a separator to the menu + +#### Method: `set_checked` + +- `command_id` the command of the item to alter +- `value` true or false + +Sets an item checked or unchecked + +#### Method: `set_enabled` + +- `command_id` the command of the item to alter +- `value` true or false + +Sets an item enabled or disabled + +#### Method: `set_visible` + +- `command_id` the command of the item to alter +- `value` true or false + +#### Method: `set_accelerator` + +- `command_id` the command id of the item to alter +- `accelerator` accelerator string + +Sets the accelerator string for the menu item + +Sets an item visible or invisible + +#### Method: `add_submenu` + +- `menu_id` the menu id to add as submenu +- `label` label for the submenu +- `command_id` command id for the submenu item + +Adds an other menu as submenu of this menu + +#### Method: `clear` + +Clears the menu of all its items + +#### Method: `popup` + +- `window_id` the window id on which to popup the menu + +Popup the menu as a context menu under the current mouse position for the window +specified by its id. + +#### Method: `set_application_menu` + +Sets this menu as the global application menu on MacOSX and X11/Unity + diff --git a/docs/api/session.md b/docs/api/session.md new file mode 100644 index 0000000..54c028c --- /dev/null +++ b/docs/api/session.md @@ -0,0 +1,137 @@ +session +======= + +The `session` object provides an API to manage sessions for a window (cookies, +storage). + +#### Constructor + +- `off_the_record` if true windows using this session won't write to disk +- `path` path under which session information should be stored (cache, storage) +- `cookie_store` whether or not to use a custom cookie store + +#### Method: `visitedlink_add` + +- `url` a link url + +Adds the specified url to the list of visited links for this session + +#### Method: `visitedlink_clear` + +Clears the visited links storage for this session + +#### Method: `proxy_set` + +- `rules` proxy rules string + +Sets the specified proxy rules (as string) for the current session + +``` + proxy-uri = ["://"][":"] + proxy-uri-list = [","] + url-scheme = "http" | "https" | "ftp" | "socks" + scheme-proxies = ["="] + proxy-rules = scheme-proxies[";"] +``` + +For example: +``` +"http=foopy:80;ftp=foopy2" -- use HTTP proxy "foopy:80" for http:// + URLs, and HTTP proxy "foopy2:80" for + ftp:// URLs. +"foopy:80" -- use HTTP proxy "foopy:80" for all URLs. +"foopy:80,bar,direct://" -- use HTTP proxy "foopy:80" for all URLs, + failing over to "bar" if "foopy:80" is + unavailable, and after that using no + proxy. +"socks4://foopy" -- use SOCKS v4 proxy "foopy:1080" for all + URLs. +"http=foop,socks5://bar.com -- use HTTP proxy "foopy" for http URLs, + and fail over to the SOCKS5 proxy + "bar.com" if "foop" is unavailable. +"http=foopy,direct:// -- use HTTP proxy "foopy" for http URLs, + and use no proxy if "foopy" is + unavailable. +"http=foopy;socks=foopy2 -- use HTTP proxy "foopy" for http URLs, + and use socks4://foopy2 for all other + URLs. +``` + +#### Method: `proxy_clear` + +Clears the proxy rules string for this session + +#### Accessor: `is_off_the_record` + +Returns whether the session is off the record or not + +#### Remote Method: `cookies_load` + +Retrieves all the cookies from the custom cookie store + +#### Remote Method: `cookies_load_for_key` + +- `key` domain key to retrieve cookie for + +Retrieves the cookies for the specified domain key. + +#### Remote Method: `cookies_flush` + +Flush all cookies to permanent storage + +#### Remote Method: `cookies_add` + +- `cookie` + - `source` the source url + - `name` the cookie name + - `value` the cookie value + - `domain` the cookie domain + - `path` the cookie path + - `creation` the creation date + - `expiry` the expiration date + - `last_access` the last time the cookie was accessed + - `secure` is the cookie secure + - `http_only` is the cookie only valid for HTTP + - `priority` internal priority information + +Add the specified cookie to the custom cookie store. + +#### Remote Method: `cookies_update_access_time` + +- `cookie` + - `source` the source url + - `name` the cookie name + - `value` the cookie value + - `domain` the cookie domain + - `path` the cookie path + - `creation` the creation date + - `expiry` the expiration date + - `last_access` the last time the cookie was accessed + - `secure` is the cookie secure + - `http_only` is the cookie only valid for HTTP + - `priority` internal priority information + +Updates the `last_access` time for the cookie specified + +#### Remote Method: `cookies_delete` + +- `cookie` + - `source` the source url + - `name` the cookie name + - `value` the cookie value + - `domain` the cookie domain + - `path` the cookie path + - `creation` the creation date + - `expiry` the expiration date + - `last_access` the last time the cookie was accessed + - `secure` is the cookie secure + - `http_only` is the cookie only valid for HTTP + - `priority` internal priority information + +Removes the specified cookie from the custom cookie store. + + +#### Remote Method: `cookies_force_keep_session_state` + +Informs the cookie store that it should keep session cookie across restart. + diff --git a/docs/api/webview.md b/docs/api/webview.md new file mode 100644 index 0000000..b35d989 --- /dev/null +++ b/docs/api/webview.md @@ -0,0 +1,241 @@ +`` +=========== + +The `` tag is available in the top-level document of any Thrust windows +and lets client code embed untrusted content securely and efficiently. The +`` runs in its own separate process and has stricter permissions than +an `