I've had more than one person offer to help me with Taffy documentation lately, and I would love to be able to open it up just like the source code of the project so that people could make proposed changes and submit a pull request. Unfortunately this is a standing request that's yet to be filled for Github Wiki's.
I think I may have found a workaround.
It takes a little bit of extra effort (only a little!) and I would only recommend it for intermediate gitter's and above. (Sorry noobs!)
Every wiki should be available as a git repo already. For example, you can see Taffy's here, and FW/1's here.
My proposed workflow is this:
Manually create a fork of the Taffy wiki on your Github account:
Create a new repository on your github account. Let's call it "Taffy-Wiki".
Clone the Taffy wiki repo to your local machine somewhere: git clone git://github.com/atuttle/Taffy.wiki.git
Remove the original "origin" remote and add your github repo as new "origin" git remote rm origin and git remote add origin git://github.com/<YOUR_USERNAME>/Taffy-Wiki.git
Make your proposed changes locally, then push them to your github account: git push -u origin master ('-u origin master' only required the first time; afterwards just do git push)
Submit a ticket to the official Taffy issue tracker requesting me to review your changes and merge them in. Please be sure to include a link to your repo and describe what you've changed.
Goto #2
I apologize if that sounds complicated, but when you think about it in comparison to making code changes and submitting a pull request, it's not that much more complex. Also, here's a script you can copy/paste into your terminal that will do the forking for you, except the repo creation:
Insert your github username for <YOUR_USERNAME> toward the end
This way anyone can submit documentation patches and I'll be able to review easily merge them in and keep the published wiki updated. (I had considered just putting the wiki source in to a folder or branch of the source repo, or its own repo, but that comes with its own challenges like keeping the published wiki updated.)
I've been working hard, in my nooks and crannies of free time, to put together and release Taffy 1.1. Lots of stuff has changed for the better, and it's a pretty sweet upgrade, if I do say so myself.
Luckily, I haven't been working alone. To date, I've had community contributions in the form of code, help testing, and advice from (in no particular order other than that with which they came to mind) Brian Panulla, David Long, Greg Moser, Dan Lancelot, Steve Rittler, and Barney Boisvert. There are more, I'm sure; and I'm deeply sorry for forgetting them/you!
But recently I realized that work has stagnated a little bit. Releasing version 1.1 has been held up for more than 5 months now almost entirely by my desire to add support for Railo. While I'm all for the open source movement (Taffy is open source after all), and the people working on and for Railo are some pretty nice guys, I just can't let that continue. So I'm going to release 1.1 soon, with or without Railo support.
Don't get me wrong, I'd still love to have it supported and I'm happy to review any pull requests anyone sends in. It's just that I've had a hell of a time getting a decent environment setup to run my tests and work out the kinks, and while there has been some support from the Railo community, I'm afraid to say it's just not been enough.
So to that end, I'm posting Taffy 1.1 Release Candidate 1 (RC1) here today. You can download the zip and play with it, but the best thing you could do would be to clone from the 1.1-rc branch on github to make it easy to get the latest updates. So what's left to do before this release candidate is declared final? Most importantly, I need to finish the documentation updates. I've got a lot done that was published earlier today, and there's still some more to do. And of course, I need people to play with it and report any bugs you find!
And, if you're in a giving mood, I'll be keeping the Railo branch up to date. This branch is designated for testing and sharing Railo-specific fixes, and then once they are confirmed working in Railo and confirmed not to break against Adobe CF, I'll merge them into whatever the current dev/RC branch is.
I really hope that the Railo community can help me finish what's left to get their platform supported, but in the end it boils down to shipping 1.1 being more important --for me, at least-- than including Railo support.
Look for a post soon outlining some of what's changed since 1.0. I'm pretty excited about it! You can get a preview of that post here on the roadmap, if you just can't wait.
Authentication is an important problem, and usually one of the first questions I get when I'm telling people about Taffy. My canned response is that Taffy does not handle any authentication for you, but it does expose some functionality for you to build authentication into your APIs.
The reason that Taffy doesn't handle authentication is because there are probably a dozen or more ways you could accomplish it (OpenID, OAuth1, OAuth2, HTTP Basic, and the list goes on...), and no one way would satisfy everyone. Trying to add multiple methods into the framework would add a lot of bulk that would be wasted by anyone not using that functionality.
To help you add authentication, Taffy calls a method in Application.cfc named onTaffyRequest, passing in all of the details of the request (verb, headers, arguments, etc) after it has parsed them from the request, but before running any of your code. This allows you to inspect the request and decide whether or not you want to allow it to continue, or redirect, or return an error or... whatever else you might want to do.
That said, people have done a few different things, and I thought it would be useful to share them with you.
Greg Mosier, who is writing an eCommerce plugin for Mura called Slatwall, posted about his solution for authentication, which denies requests that didn't originate from a user with an existing authenticated ColdFusion session.
Then, Glynn Jackson posted about his solution which uses public and private keys (kind of like SSH, but not exactly the same) to prevent unauthorized database changes. As discussed in the comments on his post, since he's not using SSL, the data is not secured in-transit; his authentication is only serving to prevent unauthorized reads and writes against his database. Anyone sniffing traffic in the middle would be able to see what the data was. Still a perfectly valid approach though, depending on your requirements.
Of course there are a lot more ways to accomplish authentication, but hopefully these examples will get you started and help you understand how onTaffyRequest works.
It seems like every time I make a promise to get something done for the community -- Taffy 1.1, bug fixes for a Mango plugin, and now this -- life has a way of making me break that promise. To wit, I was (still am) slammed at work with more than the typical workload. I'm not complaining. Job security is nice, but I feel bad for broken promises.
For those of you who attended my Taffy presentations at Philly CFUG or on The Online ColdFusion Meetup, it is mostly the same, but it did evolve a little bit. If you want a refresher, this is the most relevant version to watch.
For the slide notes, you should download this PDF, which has the slide at the top of the page, and the notes at the bottom.
Lastly, Tim Cunningham was in attendance and kind enough to record my session on video for posterity. I've embedded the two parts below. Thanks, Tim! (Also, thanks for letting me crash on a cot in your room when the hotel gave away my room on Wednesday night!)
Thanks again for coming to my session. It was my first time presenting at a conference, and to get such a positive response was amazing. I hope you got something valuable from it, and I hope to see you at a future event. :)
I'll be leaving in just a few short hours to fly to Minneapolis and attend cfObjective 2011.
In case you didn't already know, I'll be presenting on creating REST web services with ColdFusion, and of course, Taffy. My session is Friday morning at 10:15, in ballroom D3.
If my laptop battery holds out during my flights, I should be able to finish the last few tasks in time to release Taffy 1.1 at my presentation on Friday morning. Cross your fingers. (If not, it should be within a week or two!)
While I'm babbling about Taffy, I'll also mention that I've created a Google Group for it. It's kind of hard for me to believe, but adoption has been steadily increasing and I am no longer able to respond to every Taffy-related email I get in a timely manner. I'm hoping that users can help each other out via the group -- and of course we'll discuss best practices and the future of the framework there, too. If you're interested, you can find it here: https://groups.google.com/forum/#!forum/taffy-users
