izy-circus
Universal rendering component for Izyware. Circus is a browser written in pure JavaScript/HTML (self-interpreter and meta-circular evaluator). It is useful for lightweight headless rendering and building sophisticated debuggers for application and A/B testing.
INSTALLATION
Vesion 2.0 and above are deployed as an IzyCloud package which can be referenced as a content engine, for example:
bootstrap/5/circus:http
earlier versions were deployed as nodejs packages. See notes below.
USING THE TOOL
From the IzyCloud dashboard, add the following as the content engine
bootstrap/5/circus:http
Granular User Management Features
The behavior may be customized by using the following
usermetadata
keys:
- component (string)
- platformversion (number)
- bootstrapUrl(string)
- generateHtmlContentSection (boolean): When platformversion > 3, the system will by default generate the server side HTML content. Setting this flag to false will disable this behavior. This is useful for experimental accounts where the applications are still slow and it is sometimes troublesome.
Testing
Unit Tests
npm run unittest queryObject.verbose.log true queryObject.testcase ...
node cli.js method chain chain.action "//inline/bootstrap/5/uriframe:test/index" chain.queryObject.verbose true
Integration Tests
Use
npm run integrationtest queryObject.verbose.log true queryObject.testcase ...
These tests feed path strings to the izyware.com shell and test various behaviors. Note that the following:
- the current shell: If the shell path structure changes these tests will need to be updated
- anonymous and
michael.greer@izyware.com
users: these two user profiles are used for testing public and logged in behaviors where generateHtmlContentSection is expected to be on. The Michael Greer
is required for testing non-public core apps (i.e. settings area).
Local Debugging
Refer to the izy-proxy server configs.
Deployment Dependencies
//cloud/bootstrap/@version/circus:
//cloud/bootstrap/@version/sessman:api
//cloud/bootstrap/@version/uriframe:
HTML Warning Comments
In addition to providing performance and diagnostics via HTTP headers, WARNINGS are also logged as html comments. For example:
`
">setMetaData: !pulse.address || !pulse.id is missing. link will be affected !------------>
`
Izy Cloud Watch will scan your pages for warnings like this and alert if there are any content generation issues.
NOTE
for more details, visit https://izyware.com
Current Pacakges:
- bootstrap/@version/circus
Known issues
- invalidating the session (i.e. by deleting the session file) and refershing will cause 500 error
* log in, delete the session file (see accounts readme) and refresh https://izyware.com/product.
* that is because //izyware/bootstrap/5/sessman:api?whoamifull will generate an error. it should instead handle this gracefully by returning an "invalid" code to the caller and have the caller do 302 or something.
- when running on latest izy-proxy (wonder if these are timing bugs)
* the incognito mode anonymous refresh issue
* weird session bleeding issues (user 2 was used to cache marketing)
* may be just dont allow caching for logged in?
* does this make using e-tags moot
* should accept sequenceNumber, timestamp as optional params.
modtask.objects[i].imgUri += '-5-' + modtask.objects[i].sequenceNumber + '-' + modtask.objects[i].timestamp;
- use package.json and izy-proxy for testing
*
INPROGRESS_
- circus.cachebust is needed when TTL is not appropriate
- add redirect to https into circus and make it configurable
- the browsers do not send the URI fragment back to the server. therefore cut/paste in the address bar will not displaythe correct "metadata"
* this is only an issue for tools like Slack, Facebook, etc.
* possible workarounds are having the option to change url when navigating
* this should be done after performance optimization for the initial load
- fix bootstrap/5/config to grab circus from server environment
- Currently nav/multi implements frame functionality + state and Uri functionality
* snould be broken into the two pieces
* it is already being passed to circus in the bootstrapper as
modframe
- fullState is not supported for root schema
* support this and enforce length of 1
Change Log
v5.4
- 540000006: reorganize tests and standardize folder and file structure
- 540000005: handle /metagateway/address-shardIdID-itemType-sequenceNumber-timestamp url format
- 540000004: handle /metagateway/address-shardIdID-itemType-sequenceNumber url format
- 540000003: should handle /metagateway/test-content-1F4421AB816-3 gracefully
- 540000002: load images from izyware.storagedata on itemstoragedata.storagedataid
* needed for multi payload support
- 540001: circus - add izy-proxy package dependency. refactor tests.
v5.3
- 530033: serialize linkState values
* allows passing kvsValidated and objects to the values
- 530032: fix linkToHref for .. and add test case linkToHrefUriDotDot
- 530031: add
cacheselect
url and track userAgent when caching
- 530030: add TTL to cache items.
- 530029: forceFrontEndUrl only when generateHtmlContentSection is set.
* so that when logged in, refreshing should preseve the full front-end url.
- 530028: seperate the cachable content from bootstrap and standard headers, etc.
* this will make sure that the bootstrap information does not get cached.
- 530027: add whoamiExecutionContext for help with integration tests
* Now the integration tester can set session and force the whoami to run "inline"
- 530026: sessman: use current session when authorizationToken is not provided.
* useful for testing and sessman is forced to run inline.
- 200325: circus/chain: add support for link.suffix
* This is required for redirecting "public" paths have already been fixed by SEM, etc. to internal path structures, for example when user lands on
/help/browse/15
and the initial capture is:
{ workspace: "help/browse/15", app: ""}
This will be redirected to:
{ state: { workspace: "public", app: "help" }, suffix: 'browse/15' }
- 200324: circus/chain: fullState is not supported for root schema
- 200323: circus/chain improve error handling when invalid links are present.
v5.2
- do not cache when generateHtmlContentSection is set to false
- sessman: add boolean and null types to usermetadata
* allows definition of true/false boolean values and null values for JSON objects
v5
- 200321: double slash in redirect (fix)
- add session config option from usermetadata
* enables shell customization per user
- fix forcepackagereloadhack bug.
- add support for link with fullState = /
* this is needed for cross application linking (i.e. editing markdowns belonging to a collection)
- add /cachedelete url
- getMetaGatewayAddress remove https from links
* allows easy running on http
* use the same protocol as the main page
- serialize: fix bug where itemType was not used for circus.getMetaGatewayAddress
- add caching
* 141 pages would have taken 10 minutes to crawl and would spike the CPU
* page load without caching was about 10 seconds
* outages
* after caching its immediate and page load < 1s
* 141 pages took 2 minutes
- add support for groupsmembers schema
- ignore schemaUriToKVS when it does not exists
* utilizes izy-proxy feature methodnotfoundstatus=methodnotfound
- expanded the nextComponents to allow passing of parameters into the queryContent
- add generateHtmlContentSection config flag
- add the ability to specify platform versions per userId
* this will allow having a running system with existing customers on the old stuff while trying out new things and implementing new apps under new accounts for new customers
* for the first step userplatformversion option was added to the domain config
"userplatformversion":{ "124": 5, "anonymous": 5 }
- get rid of bootstrapFile and use bootstrapUrl for specifying the file
* the file://domain/path schema can be used
- implement extraction of authorizationToken from cookie and settings the session
* this is required for correct functioning of the apps on the backend
* this is also needed for platform versioning per user
- add forcepackagereloadhack
* this will work around the "cannot determine module to package mapping" when running stuff locally
- add disableAutoStart to url config
- use schemaUriToKVS, handle 301s
- enhance framesetschema error handling. deprecate framesetnav
- add new tests for href generation
- improve tests and refactor config out of tests
- have backend also use 'circus.addUriProperties' for consistenty with front-end link
- simplify viewLinks, collectionItems schemas for easier serialization into HTML
- get rid of collectionLinks. use collectionItems link property instead
* this will make generating FE html canvas easier
- implement true full path serialization for addUriProperties.hrefUri
* so both circus and front end hrefs use full path
* will allow full right click on the front end canvas as well.
- created circus.enableUrlMode chain action
- moved the engine to versioned bootstrap directory
- add hrefUri to addUriProperties for anchor elements
- add addUriProperties chain item that can be used by everybody (backend, front-end, etc.) to figure out image uris, ec/
* need to be able to augment collection items with a property for the metaurl
['circus.addUriProperties', { properties: ['imgUri'], items : collectionItems }]
v2
- retired test/lib/assert, izy-circus/test/chainitem/assert and use the izy-proxy assertion librariy instead
- support linking and uri generation for non pulse items
* fixes "Make sure that APPS have the correct image metadata" https://izyware.com/
/dashboard/view/542147/info/314
- make tests consistent with izy-proxy guidelines
- deserialize URL to support utf-8 international characters
- can communicate non 200 statuses from the api callbacks
- since apps/pulse defines the validate api, the following can now be cleanly handled
* redirect for illegal paths
* no longer need white listed base paths to know whether it should 404.
- switch to using kvsSchema instead of direct pathPattern structures
- use api schemas instead of calcValidateState and calcPulses , calcNav, etc. to query the components
* easier to implement signatures using the chains
* universally accessible
* each piece can be tested via the izy-proxy interface
* see also https://izyware.com/
/dashboard/list/542147/info/218 (consolidate into izy-circus readme)
- turn circus into a izy cloud module
* it now can be queired from the chains and referenced as a content module inside the website apps
v1
- added tests for md, sitemap, etc.
* could be done by
`
// going to the izy-circus package
node cli.js method test
`
- refactored the loadPackageIfNotPresent inside izy-circus/render/v3.js to use the configurable pkgloader using izy-proxy 2.0;
- implemented as a node package which could be used by
`
npm install izy-circus
var _circus = require('izy-circus');
var outcome = _circus.factory(config);
`
from izy-proxy local, you can simply configure the package to auto reload and do
`
node cli.js
rsync -av --progress ./* ../izy-proxy/nodemodules/izy-circus --exclude nodemodules
`