Add XSpec

[cirulls]

Summary

This pull request adds the requested file for the XSpec Docker image for XSpec. I also submitted a pull request in the docs repository.

XSpec is a unit test and behaviour-driven development framework for XML technologies. We received a feature request to provide a Docker image for XSpec.

Checklist for Review

NOTE: This checklist is intended for the use of the Official Images maintainers both to track the status of your PR and to help inform you and others of where we're at. As such, please leave the "checking" of items to the repository maintainers. If there is a point below for which you would like to provide additional information or note completion, please do so by commenting on the PR. Thanks! (and thanks for staying patient with us ❤️)

• associated with or contacted upstream?
  • https://github.com/xspec
• does it fit into one of the common categories? ("service", "language stack", "base distribution")
  • not especially -- it's a unit testing framework (so needs further evaluation)
  • closest to a "language stack" -- it's similar to go test, but for XSLT files (and as such wouldn't be included in an application image; it's used to run XSLT tests during development)
• is it reasonably popular, or does it solve a particular use case well?
• does a documentation PR exist? (should be reviewed and merged at roughly the same time so that we don't have an empty image page on the Hub for very long)
  • Add XSpec docs#976
• dockerization review for best practices and cache gotchas/improvements (ala the official review guidelines)?
  • https://github.com/docker-library/official-images#consistency
• 2+ dockerization review?
• existing official images have been considered as a base? (ie, if foobar needs Node.js, has FROM node:... instead of grabbing node via other means been considered?)
  • FROM openjdk
• if FROM scratch, tarballs only exist in a single commit within the associated history?
• passes current tests? any simple new tests that might be appropriate to add? (https://github.com/docker-library/official-images/tree/master/test)

[tianon]

Sorry for the long review delay 😞

My first question would be around how XSpec is normally used -- is it something that's part of a larger project (as a dependency), or something that's very often run standalone?

[cirulls]

@tianon: no worries, you mentioned to be patient 😉

XSpec is a testing framework for XML technologies as it is used both as standalone and as a dependency in order to test other projects. Here are a couple of examples I know of on GitHub:

• xLib
• zip_xslt

XSpec is also included in desktop software like the Oxygen XML editor (see here).

XSpec recently introduced support for Schematron (another XML technology) and there is discussion to use XSpec to test Schematron (see here).

[tianon]

Your patience is definitely appreciated. 🙇‍♂️

I've spent a little time today understanding XSpec better, and feel like I've got a good enough understanding of it now. To (horrifically) oversimplify: XSLT is an XML transformation language and XSpec is a tool for writing test suites for XSLT. 😅

So, in short, I think we're ready to actually review the dockerization/docs. 😄

Diff:

diff --git a/_bashbrew-arches b/_bashbrew-arches
index e69de29..1ae40fe 100644
--- a/_bashbrew-arches
+++ b/_bashbrew-arches
@@ -0,0 +1 @@
+xspec:latest @ amd64
diff --git a/_bashbrew-list b/_bashbrew-list
index e69de29..f325978 100644
--- a/_bashbrew-list
+++ b/_bashbrew-list
@@ -0,0 +1,2 @@
+xspec:0.5.0
+xspec:latest
diff --git a/xspec_latest/Dockerfile b/xspec_latest/Dockerfile
new file mode 100644
index 0000000..a637030
--- /dev/null
+++ b/xspec_latest/Dockerfile
@@ -0,0 +1,35 @@
+FROM openjdk:8-jre
+
+MAINTAINER Sandro Cirulli <[email protected]>
+
+ENV XSPEC_VERSION=0.5.0
+ENV SAXON_VERSION=9.7.0-18
+
+# install XSpec
+ENV XSPEC_DOWNLOAD_SHA256 d568a8b1dbc83dffb96fea477f75863a099a25a3e68c5792aa61a7cf9bfe7d6d
+RUN curl -fSL -o xspec-${XSPEC_VERSION}.tar.gz https://github.com/xspec/xspec/archive/v${XSPEC_VERSION}.tar.gz && \
+	echo ${XSPEC_DOWNLOAD_SHA256} xspec-${XSPEC_VERSION}.tar.gz | sha256sum -c - && \
+	tar xvzf xspec-${XSPEC_VERSION}.tar.gz && \
+	mv /xspec-${XSPEC_VERSION} /xspec && \
+	rm xspec-${XSPEC_VERSION}.tar.gz
+ENV XSPEC_HOME /xspec
+
+WORKDIR /xspec
+	
+# install Saxon HE
+ENV SAXON_DOWNLOAD_SHA256 b8884cff013f4169fba13751a876794952858e9003e0726d4f9cb28d8bb09448
+RUN mkdir -p saxon && \
+	export SAXON_CP=/xspec/saxon/saxon9he.jar && \
+	curl -fSL -o ${SAXON_CP} http://central.maven.org/maven2/net/sf/saxon/Saxon-HE/${SAXON_VERSION}/Saxon-HE-${SAXON_VERSION}.jar && \
+	echo ${SAXON_DOWNLOAD_SHA256} ${SAXON_CP} | sha256sum -c - && \
+	chmod +x ${SAXON_CP}
+ENV SAXON_CP /xspec/saxon/saxon9he.jar 
+
+# use non-privileged user to run xspec
+RUN groupadd -r xspec && \
+    useradd -s /bin/bash -r -g xspec xspec && \
+ 	chown xspec:xspec -R /xspec
+USER xspec
+
+ENTRYPOINT ["/xspec/bin/xspec.sh"]
+CMD ["-h"]

---

Build test of #3303; f8b5c60; amd64 (xspec):

$ bashbrew build xspec:0.5.0
Building bashbrew/cache:1955937159d7da34eba56bc3ee939771515a184f7f75175f5b9e197bb876a32d (xspec:0.5.0)
Tagging xspec:0.5.0
Tagging xspec:latest

$ test/run.sh xspec:0.5.0
testing xspec:0.5.0
	'utc' [1/4]...passed
	'cve-2014--shellshock' [2/4]...passed
	'no-hard-coded-passwords' [3/4]...passed
	'override-cmd' [4/4]...failed

The following images failed at least one test:

• xspec:
  • xspec:0.5.0

On that build failure, see https://github.com/docker-library/official-images#consistency (if you want to use ENTRYPOINT, you're going to need a small wrapper script -- I can dig up / work up some examples of what I'd recommend if you need/want them).

[cirulls]

@tianon: thanks for your feedback. Yes, your 'oversimplification' is a good summary of what XSLT and XSpec are. 😄

Regarding the failing test and the link you provided, I believe both ENTRYPOINT and CMD are needed in the Dockerfile. Is it just a matter of creating a wrapper shell script invoking /xspec/bin/xspec.sh? Any example/best practice you may provide would be very useful.

Is it possible to share the test override-cmd and how to run it so that I can make sure the required changes pass the test?

[yosifkit]

override-cmd is in the test directory of this repo. You can run the tests against an image built locally by using ./test/run.sh image-name with an optional -t override-cmd to limit it to specific tests. override-cmd runs the image like the following and checks that the output is what was expected:

$ docker run --rm image echo "Hello World-random-characters"

The point of override-cmd is to ensure that any random binary of the image can be run without having to specify --entrypoint:

$ docker run -it --rm xspec bash
$ docker run -d xspec top

It seems that you also want to allow ease of access to running xspec on a single file so that a user can do the following: 👍

$ docker run --rm -v /my-specs/:/my-specs/ xspec /my-specs/regex.xspec

Here are a couple example entrypoints that allow flag passing via CMD (ex: docker run image --arg1 --arg2 -g) that still allow any executable from the image:

• memcached: just flag passing to memcached daemon
• bash: flag passing along with zero arguments
• redis flag passing or a config file to redis-server
  • I think this one is most similar to xpsec, though you probably don't need gosu to drop to a non-root user

[cirulls]

Thanks @yosifkit for the links and the clear instructions. I'll study the examples provided, add a wrapper shell script, and make sure that the new version passes that test before committing the changes.

[docker-library-bot]

Hello! ✨

Thanks for your interest in contributing to the official images program. 💭

As you may have noticed, we've usually got a pretty decently sized queue of new images (not to mention image updates and maintenance of images under @docker-library which are maintained by the core official images team). As such, it may be some time before we get to reviewing this image (image updates get priority both because users expect them and because reviewing new images is a more involved process than reviewing updates), so we apologize in advance! Please be patient with us (and avoid poking us about your image via other communication means -- rest assured, we've seen your PR and it's in the queue). ❤️

We do try to proactively add and update the "new image checklist" on each PR, so if you haven't looked at it yet, that's a good use of time while you wait. ☔

Thanks! 💖 💙 💚 ❤️

[yosifkit]

Closing given absence of progress. We apologize for the delays with our responses. 🙇‍♂️ Not to excuse our slow or missing replies, we often have to prioritize maintaining the current images over adding new images. Thanks for your contribution.

If you'd still like to propose a new image, let us know here and we'll try to help it move along. If you've since moved on to other endeavors, we wish you the best. ❤️