millwork 0.1.0__py3-none-any.whl

millwork/ws.py

@@ -0,0 +1,220 @@
+"""The websocket endpoint: one socket per tab, speaking the protocol.
+
+Nothing the tab sends may take the loop down: a bad frame is logged and
+skipped, a handler's failure is the session's business, and only the
+socket that currently owns the session detaches it.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+from urllib.parse import urlsplit
+
+from pydantic import ValidationError
+from starlette.websockets import WebSocket, WebSocketDisconnect
+
+from millwork.protocol import (
+    PROTOCOL_VERSION,
+    Answer,
+    Cancel,
+    Command,
+    Event,
+    Hello,
+    Navigate,
+    Request,
+    ServerError,
+    pack,
+    unpack_client,
+    unpack_frame,
+)
+from millwork.session import MAX_INFLIGHT, Session
+from millwork.shell import root_of
+
+log = logging.getLogger("millwork.ws")
+
+
+def origin_allowed(ws: WebSocket, origins: list[str]) -> bool:
+    """Same origin by default; an explicit allow-list otherwise.
+
+    A browser always sends ``Origin`` on a websocket. A client without one
+    (a test, curl) is not a browser and has no cross-site protection to
+    bypass, so it is allowed.
+    """
+    origin = ws.headers.get("origin")
+    if origin is None:
+        return True
+    if origins:
+        return origin in origins
+    host = ws.headers.get("host")
+    return host is not None and urlsplit(origin).netloc.lower() == host.lower()
+
+
+async def websocket_endpoint(ws: WebSocket) -> None:
+    app = ws.app.state.millwork
+    if not origin_allowed(ws, app.origins):
+        await ws.close(code=4403)
+        return
+    await ws.accept()
+
+    async def refuse(key: str, code: int, **vars: Any) -> None:
+        await ws.send_text(pack(0, ServerError(message=app.theme.text(key, **vars), fatal=True)))
+        await ws.close(code=code)
+
+    try:
+        _, first = unpack_client(await ws.receive_text())
+    except (ValidationError, WebSocketDisconnect, KeyError):
+        await ws.close(code=4400)
+        return
+    if not isinstance(first, Hello):
+        await ws.send_text(pack(0, ServerError(message="expected hello", fatal=True)))
+        await ws.close(code=4400)
+        return
+    if first.protocol != PROTOCOL_VERSION:
+        await ws.send_text(pack(0, Command(name="reload")))
+        await ws.close(code=4426)
+        return
+
+    try:
+        user = await app.user_for(ws)
+    except Exception:
+        # Said once per attempt; the tab is told to stop, so a broken hook does
+        # not turn every open tab into a reconnect loop.
+        log.exception("identity lookup failed")
+        await refuse("something_went_wrong", 4500)
+        return
+    session: Session[Any] | None = None
+    if first.session and first.resume:
+        candidate = app.sessions.get(first.session)
+        if candidate is not None and candidate.owns_resume(first.resume) and not candidate.closed:
+            same_user = (candidate.user is None and user is None) or (
+                candidate.user is not None and user is not None and candidate.user.id == user.id
+            )
+            if same_user:
+                session = candidate
+            else:
+                log.warning("resume refused: another user")
+
+    if session is None:
+        page, params = app.resolve(first.path) or app.fallback("not_found", first.path)
+        if app.auth is not None and not page.public and user is None:
+            await refuse("sign_in_hint", 4401)
+            return
+        session = Session(app, page, params, first.path)
+        session.user = user
+        session.base = root_of(ws.scope)
+        session.client = (
+            f"user:{user.id}"
+            if user is not None
+            else f"addr:{ws.client.host if ws.client else '?'}"
+        )
+        if (
+            user is None
+            and ws.scope.get("millwork.proxied")
+            and "x-forwarded-for" not in ws.headers
+            and not app._warned_no_address
+        ):
+            # Every anonymous visitor then shares the proxy's address and one cap.
+            app._warned_no_address = True
+            log.warning(
+                "the proxy sends no X-Forwarded-For, so every anonymous visitor "
+                "counts as one client for the session cap"
+            )
+        session.connecting = True
+        if not await app.admit(session):
+            log.warning("session refused for %s: too many sessions", session.client)
+            await refuse("too_many_sessions", 4429)
+            return
+        try:
+            await session.connect_or_fall_back()
+        except Exception:
+            log.exception("connect failed for %s", first.path)
+            await ws.send_text(
+                pack(0, ServerError(message=app.theme.text("page_failed"), fatal=True))
+            )
+            await session.close()
+            await ws.close(code=4500)
+            return
+
+    send = ws.send_text
+
+    async def close_this_socket() -> None:
+        await ws.close(code=4409)
+
+    try:
+        await session.attach(send, first.seq, close=close_this_socket, send_bytes=ws.send_bytes)
+    except Exception:
+        log.exception("attach failed for session %s", session.id)
+        await ws.send_text(pack(0, ServerError(message=app.theme.text("page_failed"), fatal=True)))
+        await ws.close(code=4500)
+        session.detach(send)
+        return
+    finally:
+        session.connecting = False
+    if session.closed:
+        # Ended while it was being connected (signed out elsewhere): the tab is
+        # told now, since nothing could reach it before.
+        reason = session.end_reason or "The session ended."
+        await ws.send_text(pack(0, ServerError(message=reason, fatal=True)))
+        await ws.close(code=4409)
+        return
+
+    overflowed = False
+    try:
+        while True:
+            message = await ws.receive()
+            if message["type"] == "websocket.disconnect":
+                break
+            text = message.get("text")
+            if text is None:
+                data = message.get("bytes")
+                if not data:
+                    continue
+                try:
+                    request_id, chunk = unpack_frame(data)
+                except ValueError:
+                    log.warning("bad binary frame from session %s", session.id)
+                    continue
+                # Fed inline: a bounded stream holds this loop back when the disk is
+                # slower than the socket, which is the backpressure.
+                await session.feed(request_id, chunk)
+                continue
+            try:
+                _, msg = unpack_client(text)
+            except ValidationError:
+                log.warning("bad message from session %s", session.id)
+                continue
+            # Each message is its own task: the receive loop never waits on a handler,
+            # so an answer to an open ask (or a click during a long handler) still arrives.
+            # The session's lock keeps handlers one at a time, in order.
+            # An answer to an open ask resolves a waiting handler and starts no new
+            # work, so it passes the bound: the backlog cannot clear without it.
+            if (
+                isinstance(msg, Event | Answer | Navigate)
+                and session.inflight >= MAX_INFLIGHT
+                and not (isinstance(msg, Event) and "/@ask:" in msg.node)
+            ):
+                if not overflowed:
+                    overflowed = True
+                    log.warning(
+                        "session %s: %d messages pending, dropping", session.id, MAX_INFLIGHT
+                    )
+                    await session._send_now(
+                        ServerError(message=app.theme.text("too_many_actions"), fatal=False)
+                    )
+                continue
+            overflowed = False
+            if isinstance(msg, Event):
+                session.spawn(session.dispatch(msg), f"event {msg.name} on {msg.node}")
+            elif isinstance(msg, Answer):
+                session.spawn(session.answer(msg), "answer")
+            elif isinstance(msg, Navigate):
+                session.spawn(session.navigate_to(msg.path), f"navigate {msg.path}")
+            elif isinstance(msg, Request):
+                session.start_request(msg)
+            elif isinstance(msg, Cancel):
+                session.cancel_request(msg.request)
+    except WebSocketDisconnect:
+        pass
+    finally:
+        session.detach(send)

millwork-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: millwork
+Version: 0.1.0
+Summary: A Python framework for data tools and AI applications: one prebuilt React bundle, driven from Python.
+Project-URL: Repository, https://github.com/DvGils/millwork
+License: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: starlette>=0.47
+Requires-Dist: uvicorn>=0.35
+Requires-Dist: websockets>=15
+Provides-Extra: dev
+Requires-Dist: watchfiles>=1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="bundle/public/favicon.svg" alt="" width="72"></p>
+
+<h1 align="center">millwork</h1>
+
+<p align="center">A modern UI framework for Python</p>
+
+<p align="center">
+  <a href="https://github.com/DvGils/millwork/actions/workflows/ci.yml"><img src="https://github.com/DvGils/millwork/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/python-3.12%2B-3776AB" alt="Python 3.12 or newer">
+  <img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache-2.0">
+</p>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/readme/app-dark.png">
+  <img src=".github/readme/app-light.png" alt="A millwork page: three stat tiles with trends, a bar chart and a sortable table, in the default theme.">
+</picture>
+
+A page is a Python function of the session's state. A handler changes the
+state, the page renders again, and the browser receives a patch. The React bundle
+ships inside the package, so a project is Python only.
+
+```python
+import millwork as mw
+from millwork import ui
+from pydantic import BaseModel
+
+
+class State(BaseModel):
+    clicks: int = 0
+
+
+app = mw.App("hello", state=State)
+
+
+@app.page("/")
+def home(s: mw.Session[State]) -> ui.Component:
+    return ui.Page(
+        ui.Text(f"Clicked {s.state.clicks} times."),
+        ui.Button("Add one", on_click=lambda s, _: setattr(s.state, "clicks", s.state.clicks + 1)),
+    )
+```
+
+```
+uv add git+https://github.com/DvGils/millwork
+uv run millwork run app.py
+```
+
+## What is in the box
+
+- **A catalogue of components** on shadcn/ui: layout, text, inputs,
+  feedback, tables, charts, forms from Pydantic models, files, tasks with
+  progress, and a chat surface that streams replies from Python.
+- **One model of state.** Python owns the state; a control is owned by
+  Python or by the browser, and the page says which.
+- **Long work as tasks**, with progress, steps and cancellation drawn by
+  the page, and chat replies that stream text, reasoning and tool steps.
+- **Files over the session's socket.** Uploads, downloads and inline
+  images travel on the same connection as everything else, so replicas
+  need no sticky routing and no shared storage.
+- **Sign-in** with password, OAuth and proxy-header providers behind one
+  `on_login` hook, and a theme file in the shadcn token vocabulary for
+  colors, fonts and logos.
+- **A test harness** that drives a page without a browser: open it,
+  click, change, submit, and read what the tab would have received.
+- **One process to run.** `millwork run` serves an app on a port or a
+  unix socket, behind a proxy and under a path prefix, with a health
+  route for the host.
+
+## The manual
+
+The manual is a millwork app. Every example in it runs, with the Python
+code beside it:
+
+```
+uv run millwork docs
+```
+
+Then open http://127.0.0.1:8008. The chapters cover pages and routing,
+state and handlers, signing in, theming, testing and running, and every
+component has a live example.
+
+## Status
+
+millwork is still in beta.
+
+## Developing millwork
+
+Python is managed with uv, the bundle with pnpm; only `bundle/` needs
+Node.
+
+```
+uv run pytest -q                       # the Python suite
+uv run mypy src && uv run ruff check src tests
+pnpm -C bundle exec tsc --noEmit       # the bundle's types
+CI=1 pnpm -C bundle exec vitest run    # the bundle's unit tests
+CI=1 pnpm -C bundle build              # rebuilds src/millwork/_bundle/dist
+```
+
+A change to the bundle is committed together with the rebuilt `dist`, so
+every checkout runs without Node. The manual's pages under
+`src/millwork/manual/pages` are the gallery a bundle upgrade is judged
+against.
+
+## Releasing
+
+A release is a tag. Write the version's section in `CHANGELOG.md`, set the
+version with `uv version 0.2.0`, commit, tag `v0.2.0` and push the tag. The
+release workflow waits for approval, checks the tagged commit, builds the
+wheel, publishes it to PyPI and makes the GitHub release from the changelog
+section.
+
+## License
+
+Apache-2.0.

millwork-0.1.0.dist-info/RECORD

@@ -0,0 +1,70 @@
+millwork/__init__.py,sha256=CZe8Bh7wRwApBkNwLeS7bLJR-Rl6VFbTIcyYY-RodEs,1144
+millwork/app.py,sha256=CxlIucKFSezmH9S8hblR-J51HFIawfWuB4dP1Q4NJt4,29915
+millwork/auth.py,sha256=MFrRE-1cOyt1xfCEVMwbrqgQhBWk-SZdcV2i-PnR6Rw,33701
+millwork/chat.py,sha256=G6JigqlcOMRjN_8ohRE-2zxwqXo6UZJVHFS6EyeFfr4,14270
+millwork/cli.py,sha256=mnisqqWMFMWQyNml7ExfCdYFLAdZpK-xeCNDMBw1wKQ,11239
+millwork/context.py,sha256=648bJyGw2LrKR71dPSBIDg82L8QJBDz7R9KSjG6kfds,1185
+millwork/files.py,sha256=QsNyy2TrrQAWiOcR6ugKnLO3q0KSnDRKKj4bscKyJmw,15388
+millwork/forms.py,sha256=dIOhZBvMhGyIgeFsXLpFL1u67SwY_ezHP-4fBWJaAIY,13758
+millwork/nodes.py,sha256=XGaJFbBoE4qxzE1Fc_vA5ps-XUtHB4431S6yO7G5Cfo,11378
+millwork/protocol.py,sha256=ZWD6kNLN2LCrRqNkZtaYvBKuG6YDKTAakthYWL_B3UM,6061
+millwork/proxy.py,sha256=YCZ1SvQ_81s51kC0iXT7BfAPuxWbOuidohI-_uh6a4I,4508
+millwork/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+millwork/session.py,sha256=RErJeP4arNhlt5y7FKztnfITZxi7J2-RP2xRxCP4DWQ,59326
+millwork/shell.py,sha256=f0sRPPxNZfcQisOq3G-qw5_BF_LK5L5IZsFsfxYFzOo,8388
+millwork/tasks.py,sha256=AvNxmUMA6I10k29iwlnAmxv25TdtbIZz2VZx09yvhLk,16290
+millwork/testing.py,sha256=HjXLa9_CNYjpzZXg5YSVY3kzKrrRvbvI9nYbK7_nTn4,12517
+millwork/theme.py,sha256=BTp7bMZbFvG6ZKSNqz30etZwrpQcBqKrDBeAi3H9kHU,11843
+millwork/ws.py,sha256=oehnRm-2_e8Ocbv0oCxypH9SXWCABs62SQGHuB8vpAg,8354
+millwork/_bundle/dist/charts-inner-Cq0vWbjt.js,sha256=FmVuZOC4F79EddZkk4FLCiei5eOfbSL3n8ViFLylwdc,369971
+millwork/_bundle/dist/favicon.svg,sha256=HTy-ug2tN86ZErZk8HG0ug8vDnKwBoVMj8ocQH9Kl00,535
+millwork/_bundle/dist/geist-cyrillic-ext-wght-normal-DjL33-gN.woff2,sha256=Ixf6S7KTycCxEOGDFdUpI1xHoN3TM4zqPYx5VekniZ4,7420
+millwork/_bundle/dist/geist-cyrillic-wght-normal-BEAKL7Jp.woff2,sha256=aJRDlpSUalidFX7OADCGlgpqQBPXSoE9q3YC79s9jAk,15084
+millwork/_bundle/dist/geist-latin-ext-wght-normal-DC-KSUi6.woff2,sha256=gk9IW10m4vLaPCsjYTLs4byOTkM3NFKVC7DkBUi0MT8,16512
+millwork/_bundle/dist/geist-latin-wght-normal-BgDaEnEv.woff2,sha256=GfnJJUaqMAwxIjXjElrxuBOU2NuaS8SkJc1bZB0tVOE,29400
+millwork/_bundle/dist/geist-vietnamese-wght-normal-6IgcOCM7.woff2,sha256=j6QOXSSCR3NeuXoL1ZO4hSRAQwYA1roBNkwx_gq8H-E,8004
+millwork/_bundle/dist/icons.svg,sha256=tF-lBhlc_N70BrqfDHezbdwafCJAQJJuxwq8L96nuTo,5031
+millwork/_bundle/dist/index.global-cOFus1M1.js,sha256=0p0US_P89RK0vZmRpd0JgwHJpJjITbd-MoQJZKP4Ti8,278894
+millwork/_bundle/dist/index.modern-CITEfQrV.js,sha256=UihD1XlW673UEupdo9UZaD1FbDwV2X756tm5Ja92elo,200872
+millwork/_bundle/dist/lib-3DI92Zxk.js,sha256=oUkCDX_HFKD5sU_XE_JE19CjkYYJH1f8_OyOcrb2PY4,4354
+millwork/_bundle/dist/main-BoZpFGOH.js,sha256=gfag9n6Fi7r_MF7Vw8OBFSH787gsoPIPxPqi58QcMpc,866591
+millwork/_bundle/dist/main-F2tEXmC5.css,sha256=JzSNg0CAcfNu17ng3zi5PZ02gzAUrUyccwdYgRmnOW0,168242
+millwork/_bundle/dist/react-markdown-DLcbNoI3.js,sha256=VxVMDJEy9xzovDrp2tIKxcHDkJNya0Psev3ThneUXN0,113375
+millwork/_bundle/dist/remark-gfm-DoHjwpPg.js,sha256=kZEtxxmySzZbk5O4EfQG7yRxCXBl_xlTa9fAEPKOuyU,38021
+millwork/_bundle/dist/.vite/manifest.json,sha256=aFM9XrEsbnRKg93ejEitw60DIHJIIyM5BNBy5CCQ744,4479
+millwork/manual/__init__.py,sha256=4k-QtRiFk_P3HSWOuOks_X09gHwFuv949t9N1AeNOyY,15621
+millwork/manual/components/Hello.jsx,sha256=dW2c8g9Ix9-iY4kOoAruLYeq1iwe_6LMHXtZxWyxYAU,1064
+millwork/manual/components/Voice.jsx,sha256=1SuuaM0YZyPv-CsHCZtME0smeE70mDpHEBaeoBeco7A,1484
+millwork/manual/pages/index.md,sha256=lzqYoP_Qnh_M6WSkKav8JIGI_nuSzyqifgPTBkQjTD4,1960
+millwork/manual/pages/app/auth.md,sha256=4fnXXtHXi17WyBdIzaPi9g8jb9p277ynYt2vCrJ-knY,7530
+millwork/manual/pages/app/pages.md,sha256=rvQDk2L511OLa-dS9oT8_kC7sh4JjrLzB12EC0mfK1Y,7264
+millwork/manual/pages/app/running.md,sha256=r1l5HEJIFkowrlO1NKe4vYntyXJmo3NYPk0T4KpdX8A,10418
+millwork/manual/pages/app/state.md,sha256=tHayMopXtYKwP5td8SqVriTiBHV3gt3tTcMPvu_hBWc,4884
+millwork/manual/pages/app/testing.md,sha256=bq3FPqlPP2kQNJrnGt-Lq58ADoN-JbvPwN5F7UH-9Us,5223
+millwork/manual/pages/app/theming.md,sha256=-vZivJA4czuYQyVlaFMAidioPFYMG1V_zwb24QbfGDA,4728
+millwork/manual/pages/components/charts.md,sha256=y3hDaeT0aP0SW59jPxj--l4waUceuAH_bhe3X8QjBR8,8334
+millwork/manual/pages/components/chat.md,sha256=o7iI5LjHI6a_mDYo6Qwazu-EWETCuj0OrFiXHoWJ7eA,9152
+millwork/manual/pages/components/custom.md,sha256=r023qmWFFIgdGroATqr9-h9oi-bxA42pexP1-9_J49Y,4876
+millwork/manual/pages/components/data.md,sha256=V_oyDTJ6KT0tXyiiCOwaUsvpTO1ELhq-Kb3Pw09Lb4k,3538
+millwork/manual/pages/components/feedback.md,sha256=NF0oRBHa8IU9BngdxyhRgYHPYbCUzMp2aDYpskcP0_k,5757
+millwork/manual/pages/components/files.md,sha256=_MNjhRKzz3YHSZ8FG6PV4EKIUz3H0fFZk5sd-H14Ao0,5556
+millwork/manual/pages/components/form.md,sha256=L8tLcvLeDnn46hxUT_PA3B-rHgbpgQUB-fK_fXNh5Uc,3570
+millwork/manual/pages/components/inputs.md,sha256=r_iU33FiFcl0W124cheMEI-yRO4lykrQUfIbMgYaH8k,10251
+millwork/manual/pages/components/layout.md,sha256=17vphwaIFiOpCu37pqRCSzQDouhjpEnb1XRzTvieEHM,4315
+millwork/manual/pages/components/tasks.md,sha256=FsswConCOqzIP7ddXmI5SFZDk2C3QGKMkUNwNcFbmvQ,3619
+millwork/manual/pages/components/text.md,sha256=qWVj_K9JV6UX3yTzO3NqGxkP_iv3hzBwrUpOliBbXFE,3518
+millwork/manual/public/mark.svg,sha256=HTy-ug2tN86ZErZk8HG0ug8vDnKwBoVMj8ocQH9Kl00,535
+millwork/manual/public/theme.json,sha256=brPjaeQG-XaBtmfqGaww-c6t38Lsmh-76sDoIB4rdrI,2885
+millwork/manual/public/fonts/InterVariable.woff2,sha256=aTt31PMu6bi_yZVYm1-tXpmt8oMnOGYfVAL5l4QpqOM,352240
+millwork/manual/public/fonts/LICENSE.txt,sha256=x95laahr1Mk2gzPVRFjs6XRp0Yp8XdZ-l2FgpDqLILs,103
+millwork/ui/__init__.py,sha256=2jVD1HQzd9bH6gCH29LNRkkYyzGn-nZ-LiMOQ4SAt5k,19361
+millwork/ui/charts.py,sha256=r77njt8mbdCcy_bsNfXNuinxLUF0FK4tOQV9PqQATPU,8449
+millwork/ui/chat.py,sha256=r9pgx8BF16Hzbu2bVikEMEUEEgLiL5r3TN57_4C9sJg,3343
+millwork/ui/files.py,sha256=u0e9RRSAEms85PpvaKvBWslCPlLZRnKtF77Gk4e-Vis,3021
+millwork/ui/form.py,sha256=I2lDcp-4-ThrW3sH9YyJ_SffRVS3gC3v5w8KdRu7dbs,3942
+millwork/ui/table.py,sha256=HPNkbhb2xQkzDNYjiHv1C1st9j2JnM2BQagKQdIzoqo,4666
+millwork-0.1.0.dist-info/METADATA,sha256=J4CT2wkJNRfTr0-QsGrdb_N6FdxBmulBJuYE1yMY0yk,4539
+millwork-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+millwork-0.1.0.dist-info/entry_points.txt,sha256=BxIsShY4FbKeHxO4ayW7krZ1o66WOHNO7DV3TARo1-Q,47
+millwork-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+millwork-0.1.0.dist-info/RECORD,,

millwork-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

millwork-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+millwork = millwork.cli:main

millwork-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.