.. NutShell documentation, description .. _commands: ========================== Commands and status codes ========================== .. _request: Instructions ============ A product query may contain the following requests called *instructions* in NutShell: actions, input types and post-processing tasks. On command line, they can be set invidually or with ``--instructions`` . For logical reasons, some of them are mutually exclusive, like ``DELETE`` and ``EXISTS``. Some of them, are implicit; for example, ``MAKE`` includes ``EXISTS`` and conditionally sets ``GENERATE``. ============== ================= ============ HTTP request Command line arg ============== ================= ============ ``EXISTS`` --exists Check existence of the product ``MAKE`` --make, -m Generate file, if it does not exist (default request) ``DELETE`` --delete, -d Delete the product file in cache dir ``GENERATE`` --generate, -g Generate file, even if it exists. -- --copy, -C `file` Copy file -- --move, -m `file` Move file -- --link, -l `file` Link file ``SHORTCUT`` --shortcut Link file to short directory with original filename ``LATEST`` --latest, -L Link file to short directory, ``$TIMESTAMP`` replaced with ``'LATEST'`` ``INPUTS`` --inputlist, -I Check inputs ``TEST`` --test Check existence and permissions of directories and scripts ============== ================= ============ Some requests specify the product type, for example for ``make`` or ``exist`` commands:` ============== ================= ============ Instance type ============== ================= ============ ``FILE`` --file Target object is a file ``MEMORY`` --memory Target object resides in memory ============== ================= ============ Note: short forms of command line instructions are available in the Python version only. .. _directives: Directives ========== NutShell supports *directives*, additional instructions that define *how* a product is computed or what kind of *additional outputs* like logs should be generated. A directive *should not change the contents of the end product*. If it does, it should be applied as a *product parameter* instead, which appear in filenames as well. Products generated with same parameters but different directives yield an equivalent end result (file). As with product parameters, directives will be communicated to generator scripts as environment variables. User may define arbitrarily many directives, for example for selecting an input source from a list of equivalent data centers (mirrors). User should avoid predefined NutShell directives defined below. Built-in directives ------------------- ========== ============================================================ ``LOG`` Save log ``STATUS`` Also after successful ``MAKE`` return the status page (HTML) ``NICE`` Generate a product with lower CPU priority ========== ============================================================ Status codes ============ NutShell recycles some standard HTTP status codes [1]_ [2]_ for communicating success or failure on operations. Many of those codes can be also used by the generator scripts in describing errors or other exceptional conditions back to the hosting system, NutShell. .. _http-codes: Appicable HTTP codes -------------------- ==== ========================== ========== ========== Code Standard Enum Name NutShell Comment ==== ========================== ========== ========== 102 PROCESSING x 200 OK x Request completed successfully 403 Forbidden x Resource exists, but access restricted 404 Not Found x File not found (Generator may exist) 405 Method Not Allowed x 408 Request Timeout x 409 Conflict Contradicting parameters 412 Precondition Failed Required input missing 413 Payload Too Large Parameters imply expensive computation 415 Unsupported Media Type Unsupported file format 416 Range Not Satisfiable Parameter underflow or overflow 425 Too Early Input data not arrived 500 Internal Server Error Generator script failed 501 Not Implemented x Product generator not found 503 Service Unavailable x Busy, come back later ==== ========================== ========== ========== .. [1] https://docs.python.org/3/library/http.html .. [2] https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html