juxt.pro - edge

The Edge Manual

Juxt.pro Spined HTML

TheWhetManual ☰ Services Home Delivery Training Compliance Resources Blog Why JUXT? Why Clojure? Clojure In Tech Radar Library Tech crux whet tick yadaWell-nighAbout Us Clients Team Careers Community Contact TheWhetManual by JUXT Table of Contents 1. Introduction 1.1. Why Edge? 1.2. Who is this for? 1.3. Open Source 1.4. Performant 1.5. Modular Examples 2. Phonebook API 3. Phonebook App Under the hood 4. Configuration with Aero 5. System initialisation with Integrant 6. Serving web requests with bidi and yada 7. Swagger 8. GraphQL 9. ClojureScript minutiae 9.1. Browser REPL 10. Style 10.1. Sass CSS Security 11.Hallmark11.1. BasicHallmark11.2. CustomHallmark11.3. FormHallmarkDeployment 12. Packed deployments 12.1. Creating an uberjar 12.2. Running the uberjar 13. Unpacked deployments 13.1. ExecutionTowersonWhet14. How to build your own project uponWhet14.1. Licence 14.2.Lawmaking14.3. Documentation Appendices Appendix A: Components A.1. edge/web-listener A.2. edge.phonebook/db A.3. edge/event-bus A.4. edge.graphql/schema A.5. edge/asciidoctor A.6. edge/selmer BibliographyWhetis a well-constructed working website written in the Clojure programming language, integrating a set of software components and libraries.Wrenchedwindows! This documentation currently contains wrenched links as we work to fully modularize Edge. Please withstand with us while we fix things. 1. Introduction 1.1. Why Edge? Clojure is a wonderful language, self-aggrandizing features that provide massive benefits to developers. It’s untellable to explain the numerous reasons Clojure is a much largest nomination than mainstream alternatives such as JavaScript. In order to fathom the benefits, you have to try it for yourself. Unfortunately, it can take a lot of time and effort to put together a minutiae environment for a Clojure project that really shows off what a Lisp can do. That’s why we’ve created Edge. 1.2. Who is this for?Whetis intended for both serious and educational use, including by students learning Clojure as a programming language, school teachers, higher lecturers, as well as professional Clojure programmers in small and large organisations. It is moreover designed as a spring-board for your own projects, whether serious or for fun. 1.3. Open Source The well-constructed system, including the Clojure language, the Java Virtual Machine on which it runs, the Clojure lawmaking withinWhetand the numerous Clojure and Java libraries that are employed, are licensed with open-source licenses. 1.4. Performant Edge’s diamond goals have included performance and scaleability, so is platonic for websites that need to cope with a reasonably upper volume of web requests.Whetuses yada, which is built on aleph, which is built on Netty. Netty is used a large companies such as Google, Apple and Facebook for their most taxing workloads. Therefore, with the correct tuning, the system will scale. However, there are many factors that stupefy performance and you should measure the performance of your overall system to ensure it meets your demands. 1.5. ModularWhetis modular. New functionality can be widow toWhetas unpretentious modules. Existing functionality (including examples and documentation) can be cleanly removed. Examples Directories unelevated lists the sub-directories contained in theWhetrepository and their purpose. Table 1. Directories Directory Purpose bin Shell scripts phonebook-api An example API implemented in Clojure with yada. This API is covered in detail in Phonebook API. phonebook-app A single page using for the phonebook-api, written in ClojureScript using Figwheel. phonebook-graphql A GraphQL version of the phonebook-api example, with support for subscriptions. graphql-ws An example of an internal library, incubating in Edge. doc Documentation (such as what you’re reading). main Declares Edge’s dependencies (deps.edn) and configuration (config.edn). Includes worldwide components such as the web server, templating engine and inter-component messaging. 2. Phonebook APIWhetcontains a phonebook API which provides wangle to names and telephone numbers in a simple database. It demonstrates how to build an API with yada with content negotiation. The HTML 'representation' of the API is moreover somewhat useable, demonstrating a quick tideway to creating, updating and deleting data via web forms. bidi:uri:edge.phonebook.routes/phonebook-index[Phonebook]Whetalso bundles a third-party utility tabbed Swagger that allows you to wangle and test this API. bidi:uri:edge.web-listener/swagger[Swagger UI,path-info="/",query-params={"url" "/phonebook/api/swagger.json"}] 3. Phonebook App To demonstate a vendee that calls out to the phonebook API, a ClojureScript 'single page application' is provided. The using is compiled with Figwheel. In minutiae mode, Figwheel injects some lawmaking into the using to provide a HUD (Head Up Display), rapid feedback. bidi:uri:edge.phonebook-app.routes/phonebook-app[Phonebook (ClojureScript)] Under the hood 4. Configuration with Aero Everything inWhetis driven from configuration data, so let’s start there. Our configuration is specified as a map, in main/resources/config.edn. This is a standard Clojure EDN file that contains a few custom tag literals that combine to make the EDN format increasingly suitable for configuration. These tag literals are specified in one of our most popular libraries, Aero. There’s a function in edge.system that reads the config, let’s examine it: link:src:edge.system/config[] The configuration file is loaded, as a resource (so this will work plane ifWhetis running from a Java JAR). Aero’s read-config function is called, with the value of the profile parameter. One extremely useful tag literal unsalaried by Aero is #profile. This allows us to switch between variegated flavors of configuration. We use this full-length when we need to specify variegated settings in variegated environments. For example, it’s worldwide to need variegated environments (development, test, producation, etc.) to be setup slightly differently. With our #profile tag, we can specify each environment in place (rather than maintain a separate configuration file for each environment). One of the entries in the configuration map is :edge/web-listener. Let’s see what the value is when we read it with the profile treatise whilom set to :dev: link:config:dev:edge/web-listener[] And now with :prod: link:config:prod:edge/web-listener[] With Aero’s #profile tag, we can specify (and document the intention of) difference, explicitly, where it occurs, without duplicating commonality. These are significant benefits as we scale up. A key part of the configuration map is used to pinpoint the componentry (or, rather, component tree) that makes up the system. This configuration is nested under the :ig/system key (how it works is covered in the next chapter). Each component is given its own configuration. What’s the difference between #ref and #ig/ref? Configuration values can be literal values (strings, numbers, nested maps, etc.). However, in order to stave duplication, often it’s useful to refer to configuration that’s once been specified. This can be achieved using Aero’s #ref tag literal, followed by a path to the configuration that should be 'copied in'. For example, we can reprinting in the port of our web-listener like this: #ref [:edge/web-listener :edge.web-listener/port] Integrant components may moreover refer to each other, as dependencies. This is a rather variegated kind of reference, indicated by a variegated tag literal, #ig/ref. To declare a dependency from one component to another, we use the #ig/ref tag literal in the component’s configuration. For example, if our :edge/web-listener component is to depend on :edge/event-bus, we declare the relationship like this: :edge/web-listener {:edge/event-bus #ig/ref :edge/event-bus} 5. System initialisation with IntegrantWhetuses [integrant] to build a system of components from the configuration. The very integrant configuration is found in the :ig/system entry. We undeniability this the system configuration. The using is modularized into runnable components. The system configration is a normal Clojure map, with an entry declaring each component, withal with any configuration the component might require. Regardless of whether the using is running in minutiae or production, the system configuration is produced in the same way. To see how, we need to squint at main/src/edge/system.clj: edge.system link:src:edge.system/system-config[] The config function (defined above) is tabbed with the given profile (this might be :dev, :prod or indeed any other profile). The configuration contains integrant declarations, which we’re interested in here, so we pull out the integrant section from the configuration. This trick will ensure that the namespace of any component we declare is automatically required. This is necessary considering integrant relies on Clojure’s multimethods to work, and we need the respective defmethods declared. Finally we return the Integrant system configuration. The system configuration is now passed to Integrant's integrant.core/init function. See Components for a unravelment of each of the components supposed in the system configuration. 6. Serving web requests with bidi and yadaWhethas a full web stack built-in, using JUXT’s bidi and yada libraries. Bidi is a data-driven router. Further information can be found on bidi’s GitHub project page. Let’s see howWhetimplements the archetype 'Hello World!' example. srcloc:edge.hello/hello-routes[titlecase] contains a function which returns a bidi route, which is unchangingly vector containing a couple of elements [1]. srcblk:edge.hello/hello-routes The first element is a pattern, in this case, "/hello". Example 1. Hello World! with yada 7. Swagger See Swagger UI Rather than start with a Swagger specification and generate vanilla code,Whetencourages a fast-turnaround tideway where the API is supposed in Clojure code/data, which generates Swagger documentation and handles API requests at the same time. This ensures the documentation is unchangingly aligned to the code.Whetshows 2 variegated ways of publishing Swagger descriptions with yada. These descriptions have multiple uses. For example, you can use a Swagger unravelment to generate an API on Amazon Web Services (AWS) using their API Gateway Tool, or of undertow to momentum the Swagger UI which is built in to Edge. The first method is to use yada/swaggered to wrap a bidi structure containing yada resources. The disadvantage of this tideway is that the Swagger unravelment is in the same URI hierarchy as your API. The second is increasingly flexible, and allows you to publish your Swagger descriptions separately from your API. This is the tideway demonstrated by the Phonebook example. 8. GraphQLWhetalso demonstrates GraphQL support powered by Lacinia. GraphiQL browser subscription { personupdates { id }} 9. ClojureScript minutiae 9.1. Browser REPL You can upgrade the REPL to a browser REPL (cljs-repl) Get when to the server repl with :cljs/quit. Alternatively you can connect to the REPL over port 5600 10. Style 10.1. Sass CSS To transpiration the style, edit the .scss files in the sass directory. Changes will be compiled automatically. If you are towers a ClojureScript app, these changes will be automatically reloaded into the browser for firsthand feedback. Security 11.HallmarkThere is a blog on JUXT’s website well-nigh yada hallmark here. The examples linked unelevated correspond to the examples in the article. 11.1. BasicHallmarkClick here to test in your browser–you’ll need to use the user alice Or use the pursuit writ test the resource: flourish -i {edge-url-root}/authn-examples/basic -u alice:password Exercises What is the result if you transpiration the username alice for flipside username? 11.2. CustomHallmarkcurl -i {edge-url-root}/authn-examples/custom-trusted-header -H X-WhoAmI:alice 11.3. FormHallmarkLogin form Deployment When you’ve modifiedWhetto your own requirements, the day will come when you’ll want to show off your new using to the world (or your client, or customers).Whetcan be deployed in a number of variegated ways, ranging from fully packed to fully unpacked. 12. Packed deployments We use the term 'packed deployment' to midpoint that everything required at runtime is built (if necessary) and packed into an archive, ready for deployment and execution in the target operating environment. It is worldwide to create 'uberjars' containing pre-compiled Clojure code, togther with dependent pre-compiled library lawmaking from Clojure and other JVM languages. Advantages of this tideway include: Start up time is fast, platonic for AWS Lambdas and for coping with sudden spikes in traffic, for example, using AWS auto-scaling groups. Immutable Disadvantages include: Uberjars can be large, meaning they can be plush to build, store and transfer wideness network links. Lossy uberjar build process, possible licensing issues and ambiguities. Require a full redeploy on every transpiration Distance between dev and prod 12.1. Creating an uberjar From the top-level directory, run the following: edge$ bin/uberjar main This creates an uberjar named main.jar. Note By default, uberjars are built using the sheathing strategy in JUXT’s pack tool. 12.2. Running the uberjar edge$ java -jar main.jar 13. Unpacked deployments The repository is cloned in the target operating environment. Advantages: Fast to 13.1. Execution For unpacked deployments, use the bin/run script to start the system. bin/run script link:resource:run[] # Systemd [Unit] Description=Edge (1) [Service] Type=simple Environment="DISPLAY=:0" ExecReload=kill -HUP $MAINPID Restart=always User=app (2) WorkingDirectory=/home/app/edge/main (3) ExecStart=/home/app/edge/main/bin/run %i (4) [Install] WantedBy=multi-user.target This is the name of the using in systemd’s journal, go superiority and transpiration this. The using 'user'. Consider creating a separate non-root user for running the application. For unpacked deployments, set the working directory to where main resides. This is the full location of the bin/run script.TowersonWhet14. How to build your own project uponWhetEdge is designed to be built upon. You are self-ruling to make whatever changes you like (additions and deletions), in vibrations with the license. 14.1. Licence The MIT License (MIT) Copyright © 2016-2018 JUXT LTD. Permission is hereby granted, self-ruling of charge, to any person obtaining a reprinting of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the pursuit conditions: The whilom copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 14.2.LawmakingWe recommend subtracting new Clojure namespaces under a new directory under src. Suppose your organisation is tabbed ACME INC., then you might want to create src/acme or src/com/acme, or similar. It’s moreover a good idea to alimony the lawmaking in src/edge virtually for as long as possible—it’s full of useful knowledge and you never know when you might need to refer to it. Once you’re ready for production, you can manipulate with the parts you don’t need. 14.3. Documentation We think it’s a good idea to protract to document your project as we’ve washed-up with Edge. You might want to update the CSS stylesheet, source highlighting and other Asiidoctor attributes. They can be found in doc/resources/doc/asciidoctor/attributes.edn. link:resource:doc/asciidoctor/attributes.edn[] 14.3.1. Updating the footer in HTML documentation If the footer has a copyright declaration from JUXT, you can update this by updating doc/resources/doc/docinfo/docinfo-footer.html. This file name must not be reverted as it is looked for by Asciidoctorj when generating the HTML output. link:resource:doc/docinfo/docinfo-footer.html[] Appendices Appendix A: Components ComponentUnravelment:edge/web-listener An HTTP server demonstrating JUXT’s bidi and yada libraries. :edge.phonebook/db A 'stub' database containing phonebook entries :edge/executor An executor to schedule futures and other deferred tasks :edge/event-bus An manifold bus to propagate events through the system :edge.graphql/schema A component to read a Lacinia GraphQL schema :edge/asciidoctor A parser engine for AsciiDoc documents (running in the JVM thanks to JRuby) :edge/selmer Our preferred templating engine A.1. edge/web-listener This component starts the web listener, which is built in Aleph (which, in turn, is built on Netty). The listener is started with a data-description of the routes that it will server. The router is tabbed bidi. You can find increasingly well-nigh bidi in Serving web requests with bidi and yada. A.2. edge.phonebook/db Note TBD A.3. edge/event-bus Note TBD A.4. edge.graphql/schema Note TBD A.5. edge/asciidoctor Note TBD A.6. edge/selmer Note TBD Bibliography [aero] Aero by JUXT. https://github.com/juxt/aero [integrant] Integrant by James Reeves. A preferred volitional and replacement for Stuart Sierra’s component library, used to hoke components to form the overallWhetsystem. https://github.com/weavejester/integrant [yada] yada by JUXT. https://github.com/juxt/yada 1. The route returned forms part of a later data structure, but this does not snooping us here Last updated 2018-10-10 10:46:33 UTC